








Table of Contents 


List of Figures and Tables ix 
Preface xi 
xii What You Need 

xiii Guides to Programming the Apple II 

xiii Reference Manuals on the 6502 Microprocessor 


xiv Other Accessories 


Introduction to Assembly-Language 1 
Programming 


3 The Programming Process 

Creating an Assembly-Language Source File 

Assembling Your Program 

Testing and Verifying Your Program 

Running Assembly-Language Programs Directly From 

BASIC 

6 Running Assembly-Language Programs From a BASIC 
Program 

6 Advanced Techniques — The Apple lle Identification 
Routines 

6 A Note on the Tutorials 


or 


am ui 


es The Editor 8 


11 A Tutorial: Editing Text Files 
12 Getting Started 
14 The Editor Command Level 


Contents iii 





15 Entering Text With the Editor 

16 Displaying Text 

17 Line-Editing Text 

18 Storing and Retrieving Files 

19 Writing a Program With the Editor 

21 Leaving the Editor 

21 Using the Editor 

22 The Editor Command Level 

22 Getting Help 

23 Typing Uppercase and Lowercase Characters 

24 Executing Direct DOS Commands 

24 Saving and Retrieving Files on a Disk 

29 Manipulating Lines in the Text Buffer 

32 Viewing Your Text in the Text Buffer 

34 Changing Text Within a Line 

41 Editing Two Files at Once 

42 Altering the Display 

44 Leaving the Editor and Returning to BASIC 

Eee The 6502 Assembler 47 

3 51 Introduction to the Assembler 

52 A Tutorial: Using the Assembler 

52 Getting Started 

53 Assembling Your Program 

55 Using the Assembler 

55 Calling the Assembler 

57 Recovering From Errors 

58 Stopping Your Assembly 

59 Tre ASMIDSTAMP File 

59 Generating Assembly Listings 

65 Assembly-Language Source Files 

65 The Syntax of Assembly Statements 

73 Giving Directions to the Assembler 

74 Controlling the Overall Assembly 

78 Assigning Information 

81 Generating Data in Your Object Code 

85 Controlling Conditional Assembly 

88 Source File Directives 

91 Controlling Your Assembly Listings 

96 Using Macros in Your Assembly-Language Programs 

97 Calling Macros in Your Program Source File 

97 The Macro Definition File 


Contents 





ENPRES: r= 
4 


The Bugbyter Debugger 102 


106 Introduction to Bugbyter 

107 Restrictions on Using Bugbyter 

108 A Tutorial: Using Bugbyter 

109 Getting Started 

117 Loading Your Program 

119 Single-Stepping Through Your Program 
122 Using the Memory Subdisplay 

125 Tracing Your Program 

126 Changing Your Program in Memory 

127 Viewing a Page of Memory 

129 Using Bugbyter 

130 Relocating the Bugbyter Program 

130 Using Bugbyter in a Language Card 

131 Entering the Monitor 

131 Restarting Bugbyter 

132 Memory and the Bugbyter Displays 

132 Using the Memory Subdisplay 

133 Viewing the Memory Page Display 

135 Altering the Contents of Memory 

136 Altering the Contents of Registers 

137 Altering Bugbyter’s Master Display Layout 
139 Controlling the Execution of Your Program 
139 Using the Single-Step and Trace Modes 
148 Using Execution Mode 

150 Debugging Real-Time Code 

152 Debugging Programs that Use the Keyboard and Display 
156 Executing Undefined Opcodes 


The Relocating Loader 157 


160 Introduction to the Relocating Loader 

160 Restrictions on Using the Relocating Loader 
161 Using the Relocating Loader 

161 Calling RBOOT 

162 Using RLOAD 


The Apple lle System Identification 165 
Routines 


168 Introduction to the Identification Routine 
168 Using the Routines in Your Assembly-Language Programs 
169 Overview of the Identification Procedure 


Contents Y 





| l l l 


vi 


Appendixes 172 


An Editor Quick Guide 175 


175 Editor Commands: A Functional Summary 
175 Executing Direct DOS Commands 

175 Storing and Retrieving Files From a Disk 
176 Manipulating Lines in the Text Buffer 
176 Viewing Your Text in the Text Buffer 

177 Changing Text Within a Line 

177 Editing Two Files at Once 

177 Altering the Display 

178 Leaving the Editor 

178 Calling the Assembler 

179 Editor Commands: An Alphabetic Summary 
182 Edit Mode Keystroke Summary 


6502 Assembly Language Summary 183 


183 Mnemonic Summary 
185 Addressing Mode Summary 
185 Assembler Directive Summary 


A Bugbyter Quick Guide 187 


187 Bugbyter Command Level 

187 General Commands 

187 Command-Line Editing 

188 Memory Reference 

189 Register Reference 

189 Trace/Single-Step Mode 

190 Disassembly Options for Trace/Single-Step 
190 Breakpoints 

191 Debugging in Execution Mode 

191 User Soft Switches 


Error Messages 193 


193 Editor Error Messages 

193 Editor's DOS-Error Messages 

195 Editor Command-Error Messages 

197 Assembler Error Messages 

197 Assembler'’s DOS-Error Messages 
199 Assembler Syntax-Error Messages 


Contents 


Object File and Symbol Table Formats 


207 Object File Format 
209 Symbol Table Formats 


Editing BASIC Programs 
211 Using the Editor to Edit BASIC Programs 


The SWEET 16 Interpreter 


213 A 16-Bit Pseudomachine 

214 SWEET 16 Interpreter Operation 
215 SWEET 16 Instruction Summary 
215 Register Instructions 

215 Control Instructions 


System Memory Usage 


217 The Editor/Assembler 
218 The Bugbyter Debugger 


Editor/Assembler File Components 
219 The EDASM Files 

220 Making a HELLO Program 

Index 

Bugbyter Quick Guide 


Editor and Assembler Quick 


| Reference Guide 


Contents 





207 


211 


213 


217 


219 


221 


vii 


Figures and Tables 





List of Figures and Tables 


14 


40 


62 
65 


109 
110 
111 
112 
113 
113 
114 


117 
140 
143 
146 
151 


161 


Chapter 1 
Figure 1-1 


Chapter 2 
Figure 2-1 


Table 2-1 
Chapter 3 


Figure 3-1 
Figure 3-2 


Chapter 4 


Figure 4-1 
Figure 4-2 
Figure 4-3 
Figure 4-4 
Figure 4-5 
Figure 4-6 
Figure 4-7 


Table 4-1 
Table 4-2 
Figure 4-8 
Table 4-3 
Table 4-4 


Chapter 5 
Figure 5-1 


The Process of Assembly-Language 
Programming 


Editor Features Accessible From the Editor 
Command Level 
Edit Mode Keystroke Summary 


A Typical Assembly Listing 
A Sample Symbol Table Listing 


Bugbyter’s Master Display 

The Register Subdisplay 

The Stack Subdisplay 

The Code Disassembly Subdisplay 

The Memory Cell Subdisplay 

The Breakpoint Subdisplay 

Bugbyter Command Line Allows You Access to 
All Features 

Bugbyter Command-Line Editing Functions 
Trace and Single-Step Keystroke Commands 
The Breakpoint Subdisplay 

Code Disassembly Display Options 

Bugbyter Real-Time Soft Switches 


Using RBOOT and RLOAD Routines in Your 
BASIC Program 


Figures and Tables ix 


168 


207 


217 
218 


Chapter 6 
Table 6-1 
Appendixes 
Table E-1 


Figure H-1 
Figure H-2 





Identification Procedure Return Values 


Relocatable File Format 


Memory Map of the 64K Editor/Assembler 
Memory Map Showing Locations of Bugbyter 
and Your Program 


Figures and Tabies 





Preface 





Preface 


The DOS Programmer's Tool Kit Volume II disk contains everything 
you need to program your Apple || system in its native language. 
These 6502 assembly-language programming tools include 


èe an Editor—to help you create assembly-language source 
programs 


èe an Assembler—to translate your assembly-language source 
programs into executable 6502 object programs 


e the Bugbyter Debugger—a powerful debugging tool to assist 
you in testing and debugging your programs 


èe a Relocating Loader—to allow you to load and execute your 
assembly-language programs during the execution of a BASIC 
program 


e two Identification Routines—to allow your BASIC and 
assembly-language programs to identify whether they are 
executing on an Apple Il, Apple |i Plus, or Apple lle system. 


This manual explains how you can use these tools to create and 
execute assembly-language programs on your Apple Il, 

Apple || Plus, or Apple lle computer. In separate chapters, each of 
these programing tools—the Editor, the Assembler, and the 
Bugbyter—is described in detail. Each chapter consists of 


è an introduction to the programming tool 

è a tutorial demonstrating how you can use the tool 

e a reference section describing how to use the capabilities of 
each tool. 

After reading this manual and completing the tutorials, you will 

know how 


è to create and modify source files using the Editor; 
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è to generate an executable program using the Assembler; 


è to test the execution of your programs using the Bugbyter and 
to fix any errors that you find. 


This manual does not teach you how to program in assembly 
language. It is written for people who are familiar with 
programming in at least one language (BASIC or Pascal) on an 
Apple II computer system, and who have read at least one book on 
6502 assembly-language programming. 


What You Need 


To use the assembly-language tools included in this tool kit, you 
will need 


è an Apple Il, Apple |i Plus, or Apple Ile computer with at least 
48K of RAM memory 


è a video monitor (The Editor and the Bugbyter do not operate 
properly if you use an external terminal.) 


è at least one disk drive and controller card. 


Although it is not required, you may also find that a printer can be 
very helpful, since you may want to print your assembly listings 
and use these listings to keep track of your assembly-language 
programs. 


Before you continue reading this manual, you should be familiar 

with 

è how to set up and run your Apple || system (described in the 
owner's manual that came with your Apple || system) 


è how to manipulate disk files using DOS 3.3 (described in the 
DOS User's Manual) 


e how to use elementary 6502 assembly-language programming 
concepts. 


You may want to read one of the many guides to assembly- 
language programming on the Apple |i and the 6502 (the 
microprocessor inside your Apple ||) before you read this manual. 
There are several excellent reference manuals. 
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Guides to Programming the Apple II 


Marvin De Jong, Apple II Assembly Language, 1982, Howard 
Sams & Co., Inc., 4300 W. 62nd St., Indianapolis, IN 46268 


A complete manual, with an excellent introductory section, 
written using an early version of the Apple |! 
Editor/Assembler. 


Randy Hyde, Using 6502 Assembly Language, 1981, DATAMOST 
Inc., 19273 Kenya St., Northridge, CA 91326 


A thorough manual on the Apple Il, including many tables 
and an introduction to the Apple SWEET 16 ROM-coded 
numeric routines. 


Lance Leventhal, 6502 Assembly Language Programming, 1979, 
Osborne/McGraw-Hill, 630 Bancroft Way, Berkeley, CA 94710 


A quite complete guide to Programming the 6502, 6520, and 
6522. 


Reference Manuals on the 6502 Microprocessor 


Programming Manual, MCS6500 Microcomputer Family, 1976, 
MOS Technology, 950 Rittenhouse Rd., Norristown, PA 19401. 
Pub. #6500-50A 


The standard reference for programming the 6502 by the 
company that designed the 6502 microprocessor. 
R6500 Programming Manual, 1979, Rockwell International Corp., 
PO Box 3669, Anaheim, CA 92803 
An excellent alternative to the MOS Technology manual: this 
manual also includes a programming reference card. 
6502 Microprocessor Instant Reference Card. 1980, Micro Logic 
Corp., POB 174, Hackensack, NJ 07602. Product #101A 
A comprehensive single-card chart of everything you want to 
know about programming the 6502. 
Applications Information SY6500 Microprocessor Family, 1980, 
Synertek Inc., POB 552-MS/34, Santa Clara, CA 95052 


An in-depth pamphlet on the internal operation of the 6502 
microprocessor, including complete opcode timing 
diagrams. 
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Introduction to 
Assembly-Language 
Programming 


Assembly-language programming is a powerful technique for 
getting the most out of your Apple Il, Apple II Plus, or Apple Ile 
computer. The programming tools that came with this tool kit will 
help you write, assemble, and debug assembly-language 
programs that you can run on any Apple II system. The overview in 
this chapter explains how you can use these tools to create 
working assembly-language programs. 


The Programming Process 


Any program starts as an idea or a task that you want to 
accomplish. As you organize your thoughts about how your 
Apple |i can accomplish your task, you define the logic of a 
program. A program is merely an ordered set of instructions 
designed to accomplish a specific task. 


Translating these thoughts into a working Apple II assembly- 
language program is a process that has several distinct steps. 
These steps are 


1. Creating an assembly-language source file using the Editor; 


2. Assembling your source file using the Assembler to create an 
executable object program; 


3. Testing and debugging your program to ensure that it contains 
no errors; 


4. Running your working program, either as a stand-alone 
program or in conjunction with a BASIC program. 
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Figure 1-1. The Process of Assembly- 
Language Programming 
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j 
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Figure 1-1 illustrates this assembly-language programming 
process. 














Program Concept or 
Task to Implement 


1. Using the Editor, create 
a program source file. 


Program Source File 
(text file of assembly- 
language statements) 


2. Assemble your program source 
file using the Assembler. 


Object Program 
(binary file of 6502 
machine codes and data) 


3. Test and debug your program. 
if necessary, return to Step 
1 to make permanent changes. 


A Working 
Assembly-Language 
Program 
4. Use your program either by 
itself or in conjunction 
with a BASIC program. 
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How to use the Editor: see Chapter 2, 
which also includes a tutorial. 


Assembly-language source files are 
files of text characters that represent 
assembly-language instructions and 
operands. An operand is the address or 
data that the instruction acts upon. 


Mnemonics represent individual 
assembly-language instructions. An 
identifier is a symbolic name that 
represents an address or a data 
element. 


How to use the Assembler: see 
Chapter 3, which also contains a 
tutorial. 


How to use Bugbyter: see Chapter 4, 
which also includes a tutorial. 





Creating an Assembly-Language Source File 


In translating your thoughts into an actual assembly-language 
program, you use the Editor included in this tool kit to write 
assembly-language instructions into a text file and save this text 
file on a disk. 


The text files you create using the Editor that contain assembly- 
language instructions are called assembly-language source files. 
An assembly-language source file is not an executable program: it 
is an organized file of text characters that represent assembly- 
language instructions and operands. In this source file you use a 
number of three-letter sequences, called mnemonics, to 
represent individual assembly-language instructions. You can 
represent an address or an element of data in your program either 
explicitly or by assigning it a symbolic name; you can refer to it by 
this name. These symbolic names are called symbols or 
identifiers. 





Assembling Your Program 


To translate your assembly-language source files into executable 
object code, you use the Assembler that is included in this tool kit. 
The Assembler is a portion of the combined Editor/Assembler 
program. 


The Assembler translates the instruction mnemonics in your 
source file into actual machine instruction codes, and translates 
the identifiers that you used into the actual data or memory 
references to be used by your computer. The Assembler then 
stores the assembled program on a disk in the form of a binary file. 





Testing and Verifying Your Program 


Before you try to run your assembly-language program, you want 
to make sure that it executes correctly. You can test your program 
(and fix any errors that you find) using the Bugbyter program 
included in this tool kit. Using Bugbyter, you can easily step 
through any portion or portions of your assembly-language 
program, checking that each instruction executes properly and 
that the correct data is written to the proper locations. Bugbyter 
visually shows you every action taken by your Apple || when it 
executes an assembly-language instruction. 
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The DOS User's Manual describes how 
to use the BRUN command. 


Relocating Loader subroutines: see 
Chapter 5. 


Identification subroutines: see 
Chapter 6. 





Running Assembly-Language Programs Directly From 
BASIC 


Depending upon your program, the binary files created by the 
Assembler can form a complete executable program. To run this 
executable program on your Apple ll, you simply use the DOS 
BRUN command from either Applesoft or Integer BASIC. 





Running Assembly-Language Programs From a BASIC 
Program 


You may have written your assembly-language program as a 
subroutine that you intend to call during the execution of a BASIC 
program. This combines the advantages of both BASIC and 
assembly-language programming. To call your assembly-language 
subroutine from a BASIC program, you can use either the BASIC 
BLOAD command, or for greater flexibility you can use the 

Relocating Loader subroutines (RBOOT and RLOAD) that are 

included in this tool kit. m 





Advanced Techniques— The Apple lle Identification 
Routines 


When you are writing your assembly-language programs to run on 
more than one Apple II system, you may want to take advantage of 
the unique features of the system on which your program is 
currently running. To do this, your program has to identify the 
Capabilities of that particular Apple Il, Apple |i Plus, or Apple lle 
computer. 


To help you to write your programs to do this, two identification 
subroutines are included in this tool kit. One identification routine 
is an assembly-language subroutine that you can include directly 
in your assembly-language source file; the second is written as a 
BASIC subroutine that you can call as part of a BASIC program. 


A Note on the Tutorials 


The tutorials in Chapters 2, 3, and 4 are designed to introduce you 
to assembly-language programming using the programming tools 
in this tool kit. In the Editor tutorial, you will create an assembly- 
language source file and store this file on a disk. In the Assembier 
tutorial, you will assemble this source file and produce an 
executable object or binary program. In the Bugbyter tutorial, you 
will test the operation of this binary program and verify that it 
executes correctly. 


introduction to Assembly-Language Programming 





Since each tutorial builds on the results of the earlier tutorials, go 
through them in sequence so that you will have the proper files 
ready when you need them. Although you don't have to do the 
tutorials to understand the tools that are described in this manual, 
you will probably find the tutorials to be the quickest way to begin 
using these tools to program in assembly language. 


Before You Start: Before you use any of the tools in this tool kit, you 
should make a backup copy of your DOS Programmer’s Tool Kit disks. 
The DOS User’s Manual that came with your disk drive contains a 
complete explanation of how to make backup copies of your disks. 
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Changing Text Within a Line 
Searching Text 
Changing Text 
Changing the Command Delimiter 
Entering Edit Mode 
Character Editing Using Edit Mode 
Editing Two Files at Once 
Altering the Display 
Setting Tabs 
Using a 40- or 80-Column Display 
Truncating the Display 
Leaving the Editor and Returning to BASIC 
Entering the Monitor 
Identifying the Absolute Location of Text in Memory 
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The Editor's text buffer holds more than 
26,000 characters. This lets you edit 
assembly-language source files about 
1300 lines long (if an average line 
contains 20 characters). 


A line of text is a sequence of up to 
254 characters ending with (RETURN). 


You can use the Editor to edit DOS 
EXEC files or BASIC program source 
files. See Appendix F. 


Appendix A contains a summary of the 
Editor commands and functions. 


The Editor 


The Editor program in this tool kit is a tool for creating and 
modifying blocks of text that you can store as DOS 3.3 text files. It 
lets you manipulate any file of text that fits in the Editor's text 
buffer. Typically, you use the Editor to create assembly-language 
source files that you can later use with the Assembler. 


You can edit individual characters in your text file, and move or 
edit whole lines of text. The Editor treats each line of text as a 
single unit of information: most of the commands you type to 
manipulate your file will refer to a particular line or group of lines. 
The Editor keeps track of every line in your file and lets you refer to 
a particular line using that line’s relative position from the start of 
your file. 


This chapter describes how you use the Editor to create and 
modify text files and to store them on a disk: 


è A brief tutorial introduces the Editor, showing you how to create 
and modify an assembly-language source file. You will use this 
assembly-language source file later when you work through the 
tutorials on the Assembler and the Bugbyter debugger. 


e The remainder of this chapter contains a detailed description of 
the functions that you can perform using the Editor. 


A Tutorial: Editing Text Files 


This tutorial teaches you the basic editing commands that you 
need to create assembly-language source files using the Editor. 
When you finish with this tutorial, you will know how 


è to start the Editor program; 
è to create a text file by typing lines of text to the Editor; 


è to edit or change the lines in your text file using the Editor 
commands; 


è to store your text file on a disk; 
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Always press (RETURN J after typing an 


instruction. 


A 48K Apple || system may show a 
slightly different screen message. 


The Assembler ID Stamp is a short text 
file used to store a serial number and 
date on each of your source disks: see 
Chapter 3. 
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è to retrieve your text file from a disk to revise it using the Editor; 


e to store your text as an assembly-language source file on your 


system disk. 





Getting Started 


What You Do 


1. Insert the DOS 
Programmer's Tool Kit 
Volume li disk into your disk 
drive and turn on the power to 
your Apple Il. 


2. From this Applesoft/DOS 
command level, type 


RUM EDASM 
and press (RETURN). 


When the Editor finishes loading the pro 


display: 


EQITOR-ASSEMBLER 


LOADING EDASMe4, = 
LOROING EDRSMe4, 3 
LOAOQING EDRSMs4, 4 
LOADING EDASME4. S 
LOROING EDASME4., 5 
IHSERT SOURCE DISKETTE ANOD 


What Happens 


When your Apple II has loaded 
the Applesoft system, you 

see the Applesoft prompt 
character ()). 


Your Apple II loads the 
Editor/Assembler system. 


m, you see this screen 


PRESS RPETURNS 


This message tells you that you may take your system disk out of 
the disk drive and insert a program source disk if you prefer. Since 
you will not be using large amounts of disk space during this 
tutorial, you can leave the system disk in the drive. Be sure that 
you make a backup copy of your system disk before you proceed. 





3. Leaving the system disk in 
your disk drive, press (RETURN). 


The Editor 


The Editor reads the current 
Assembler ID Stamp from your 
system disk and displays it on 
the screen. The 

Assembler ID Stamp is a 17- 
byte ASCII file with the name 
ASMIDSTAMP that stores a 
serial number and date stamp 
on your source disks. The 





EDITOR-ASSEMBLER -- 


LOADING EDASM64.2 
LOADING EDASMS4.3 
LOADING EDASMe4+.4 
LOROING EDASM64.5 
LOADING EDASME4. E 
CURRENT ASSEMELER IO 


OO-MMM-Y'Y #8880808 





Assembler uses this 
ASMIDSTAMP to help you keep 
track of your assembly- 
language source listings and 
disks. Although the Assembler 
does not check the format of 
this file, the following format is 
suggested: 


dd-mmm-yy #123456 


The Editor allows you to edit 
these 17 characters to set the 
current date. There is no 
required format for these 
characters; you can type the 
date any way you wish. 


STAMP IS: 





4. Use the arrow keys to move 
the cursor, then type in the 
current date for the 
Assembler ID Stamp, or simply 
press to accept the 

ID Stamp as it is shown. Make 
sure that the cursor is at the 
right of the Assembler ID Stamp 
before you press to 
accept all of the characters on 
the line. 
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BY JOHN ARKLEY 
Cy 


APPLE COMPUTER 
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COPYRIGHT 1382 
INC 


After you press (RETURN), the 
Editor saves the updated 
Assembler ID Stamp back onto 
your source disk. You then see 
a colon prompt and the cursor 
in the lower-left corner of the 
screen. This shows that you are 
now at the Editor command 
level. 
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Editor prompt character = colon (:). 


Figure 2-1. Editor Features Accessible 
From the Editor Command Level 
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The Editor Command Level 


You are in the the Editor command level whenever you see the 
colon (:) prompt and the cursor at the left margin. 


By the Way: For a 40-column display, the cursor appears as a blinking 
underline character. If you are using an Apple || system with an 80- 
column text card, the cursor appears as a solid, nonblinking box. 


When you are at the Editor command level, you can type a wide 
variety of commands to access all of the capabilities of the Editor: 
you can add information to the text buffer, change information in 
the text buffer, and write information from the text buffer to a disk; 
you can also call the Assembler. Figure 2-1 shows a diagram 
representing all of the features you can access from the Editor 
command level. 





The Editor 





The text buffer is a memory area to 
hold your text. 


Use the File command to see 
information about your file and the text 
buffer. 


Use the Add command to enter !nput 
mode to add lines of text to the text 
buffer. 


Press (RETURN J after typing each line 


of text. 


In Input mode, the Editor interprets 
SPACE } (a space character) as a tab. 


To end Input mode, press 
CONTROL)-(Q), and press (RETURN). 








Entering Text With the Editor 


When you first start the Editor, the Editor creates an area of 
memory, called the text buffer. This text buffer is empty until you 
put some characters or text into it. 





1. To see the size of the text 
buffer, type 


PILE 


and press (RETURN). 


‘FILE 


A} j S6, WV 8 
8 BYTES USED 
26880 BYTES REMAINING 


2. To add some lines of text to 
the text buffer, when you see 
the colon prompt, type 


(A) 
and press (RETURN). 


3. Type the following lines of 
text, exactly as they appear 
below. After typing each line, 
press (RETURN). 


(SPACE) R G $1000 
START 

LO (SPACE)# ECG 
(SPACE)L C's #4 


4. When you finish typing these 
lines, press after the 


last line, press (CONTROL)-(Q), 
and then press 


a second time. 
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The Editor displays three lines 
of information: the current 
filename (there is none), the 
current disk drive, slot, and 
volume; the number of bytes 
used in the text buffer; and the 
number of unused bytes 
remaining in the text buffer. 
Your display looks something 
like this: 


The Editor displays the number 
1 to signify that the next line 
you type will be added to the 
text buffer as the first line of 
text. 


The Editor accepts the lines of 
text as you type them and 
places them into the text buffer. 


Typing (CONTROL)-(Q) and then 
pressing ends the 
Editor's Input mode and places 
you back at the Editor 
command level. 








Use the Print command to display lines 
of text from the text buffer. You can also 
use this command to obtain printed 
copies of your files. 


Use the List command to display lines 
of text, including relative line numbers. 


A relative line number is the position of 
a text line relative to the beginning of 
the text buffer; these numbers change 
as lines of text are inserted and deleted. 
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Displaying Text 





1. To view the lines of text that The Editor displays the text that 


you just typed into the text you typed and inserts extra 
buffer, type spaces wherever you typed a 
space character. 

(P) 
and press (RETURN). 

+P 

ORG #1000 
START LOY #$COB 
n LDX #0 





Notice: The Editor interprets space characters in your text as tab 
characters. The Editor’s default tab settings align the text in a 
reasonable format for assembly-language source files. = 


2. To list your text, including the The Editor redisplays the lines 


relative line numbers, type in the text buffer: 
and press (RETURN). 
e 
1 ORG #1000 
2 START LOY #500 
3 LOX #6 





A relative line number is simply the position of each line of text 
relative to the beginning of the text buffer; line number two is 
always the second line of your file, and so on. Relative line 
numbers have nothing to do with any characters or numbers 
stored in your text file. This means that if you insert or delete lines 
of text within your file, the relative position of all subsequent lines 
of text will change. 


Relative Line Numbers: The Editor's relative line numbers should not 
be confused with statement numbers you might have used in BASIC 
programs. These BASIC statement numbers are actual numbers that 
you stored as part of the program text. If you are using the Editor to 
edit a BASIC program, you see two numbers associated with each line: 


è the relative line number calculated by the Editor 
è the statement number that is part of every BASIC statement line. 


The Editor 





Use the Edit command to place the 
Editor in Edit mode to allow you to 
modify the text in the text buffer. 








Line-Editing Text 


When you make typing mistakes, you can easily fix them by using 
the Edit command. 





1. To edit each line of your text The Editor displays the first line 
in turn and fix any typing errors, of your text on the screen, with 


type an inverse-video cursor 
© positioned over the first 
character of the line. 


and press (RETURN). 


1 # ORG #14088 


Remember: The first character that you typed was (SPACE). Since it is 
not a visible character, the cursor doesn’t appear in inverse video. Use 
to move the cursor to the next character to see the cursor in 
inverse video. 


You can now edit the contents of this edit line by using the 
following procedure: 


è To move the cursor along the line, use (—) and (—). 


@ To replace a character, type the new character over the old 
character. 


è To delete a character, place the cursor over that character and 
press (CONTROL)-(0). 

è To insert a character, place the cursor over the character that 
will follow the character you are going to insert, and then press 
(CONTROL)-(1 ). Type the characters you want to insert. When you 
are done, press (—) or to end the insertion. 

èe To accept the edited line as it appears on the screen, 
press (RETURN). 

2. Follow the procedure above As you press after 

to edit each line of your text each line, the Editor 

until it appears exactly as incorporates all the changes 


shown in the previous sections. you made to the line displayed 
When no errors remain, press on the screen, and then 

until you are back at displays the next line for you to 
the Editor command level. edit. 
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Use the Save command to save the 
text buffer in a disk file. 


The Editor's CAT command is simply a 
shortened version of the DOS 
CATALOG command. E 


The Editor creates only text files. 
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Storing and Retrieving Files 


When you are back at the Editor command level, you can save your 
text on the system disk. 


1. To save your text, type The Editor saves your text in a 
e : aged text file using the name 
Z En H RAR 
AWE TES TERMAS TESTPROGRAM. 

and press (RETURN). 

2. To verify that your text file The Editor displays the 

was created correctly, type contents of your disk, with the 
-AT text file TESTPROGRAM shown 


at the end of the other files. 


and press (RETURN). You may 
have to press (RETURN) a 
second time to see all of the 
files on the disk. 


‘CAT 
DISK VOLUME 186 


A 664 HELLO 
B oiz . 


T 962 TESTPROGRAM 


Note that your file has the symbol T for text shown next to the 
TESTPROGRAM filename in the catalog. The Editor creates only 
text files; there is no difference between your assembly-language 
program and any other type of text file. 
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Use the New command to clear the text 
buffer. 


Use the Load command to load a text 
file from a disk into the text buffer. 


3. To show that your text is still 
in the Editor's text buffer, type 


and press (RETURN). 
4. To clear the text buffer, type 
HEH 


and press (RETURN). 


5. To reload into the Apple II's 
memory the text file that you 
just saved onto your disk, type 


LIAC TESTFROGRAM 


and press (RETURN). 


6. To see that your text is now 
back in the text buffer, type 


and press (RETURN). 





The Editor displays the 
contents of the text buffer, 
showing that your text is still 
there as well as on your disk. 


The Editor clears the text 
buffer, so you can type in new 
text or perform some other 
function. If you type 

and press (RETURN), the 
Editor shows you that there is 
nothing in the buffer. 


The Editor loads your text file 
from the disk into the text 
buffer. 


The Editor displays the text on 
your screen, exactly as it looked 
before you saved it. 





Writing a Program With the Editor 


You have written the first three lines of an assembly-language 
source file that you now have in the text buffer. To finish this 
program, you will add more lines to the text buffer and then save 


the final version on a disk. 


1. To begin adding more lines, 
type 


(A) 
and press (RETURN). 


A Tutorial: Editing Text Files 


Notice that the relative line 
number 4 appears before the 
prompt. You are now ready to 
enter the rest of your program. 
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2. Type the following lines. After 
each line, before pressing 
(RETURN), make sure that the 
line is typed exactly as it 
appears below, including 
spaces. 


LCF (SPACE). £ F (SPACE)S TORE 
(SPACE) I Mi 

(SPACE)|_ F (SPACE) #5 

(SPACE)E HE (SPACE)L OGF 
(SPACE) T = 

STORE ENY 

TA 

(SPACE)= TA(SPACE)JELIFF , * 
(SPACE)F' T 3 

(SPACE)C =(SPACE)FEC, FH 

ELIF F (SPacCE)C 3(SPaAce)148,. fag 


By the Way: If you want to return to the Editor command level when you 


finish typing, press (CONTROL)-(Q) and then press (RETURN). 


3. To List what you've typed, The Editor displays the text 
type lines that you typed. Your 
rogram should appear exacti 
© prog pp y 
as shown: 

and press (RETURN). 

1 DRG ${10ġġ 

2 START LOY #3008 

3 LOX #2 

4 LOOP JSR STORE 

5 INK 

= CPX #5 

? BNE LOOP 

3 RTS 

9 STORE INY 

18 TYR 

11 STA BUFF, x 

12 RTS 

13 DS $ED, $00 

i14 BUFF DS 10, $06 


4. if there are any mistakes, use 
the Edit command you just 
learned to correct these errors. 
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Use the End command to leave the 
Editor and return to Applesoft BASIC. 


When you type EHC, if you are using an 
80-column text card in your Apple II, 
your video display reverts to 

40 columns. 





5. When you have finished, type The Editor saves your 
completed assembly-language 











SAWE 
' program on your disk, using the 
name TESTPROGRAM that you 

and press (RETURN). used to load your file. 
Leaving the Editor 
1. To leave the Editor and You see the Applesoft prompt 
return to BASIC, type (]). 
EHCI 
and press (RETURN). 





Do It Again: If you want to practice the tutorial some more, when you 
see the Applesoft prompt, type MAF ILES 5 and press (RETURN). 
Then type CALL 2475 and press again. You are back at the 
Editor command level when you see the colon prompt. 


You have now completed the tutorial. In it, you learned how to use 
the Editor to do a variety of tasks. You now know how 


to start up the Editor; 


to enter text into the Editor's text buffer: 


to edit text in the text buffer: 


to view your text that is in the Editor's text buffer; 


to save your text into a text file on a disk; 


to retrieve your text file from the disk to edit and then save it 
again. 


You will use the assembly-language source file you just created in 
the tutorials on the Assembler and the Bugbyter debugging 
program. Do not delete this text file from your disk if you want to 
do these other tutorials. 


Using the Editor 


The preceding tutorial introduced you to some of the basic 
capabilities of the Editor. In the sections that follow, all these 
capabilities are described in more detail, plus other capabilities 
that are not included in the tutorial. 
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Lowercase letters shown in a command 
name indicate optional characters that 
you need not type. 


The colon (:) is the Editor's command 
delimiter. 


A 


To get help, type a ? to view the Editor's 
reference card. 





The Editor Command Level 


You are at the Editor command level whenever you see the colon (:) 
prompt character, followed by the cursor, at the left margin. You 
can access all the Editor features by typing commands from this 
level. 


When you type these commands, you can often abbreviate the 
command names to just one or two letters. In the remainder of this 
chapter, command names are shown with the required letters in 
uppercase and any optional letters in lowercase. When you type 
the command, you can type in either uppercase or lowercase, and 
include as many of the optional characters as you wish. The Editor 
ignores any spaces that you insert before or between the 
command and its parameters. 


You can type more than one command on a line. This allows you to 
do several editing operations at once. To separate each command 
on the line, you must type the Editor command delimiter, a colon. 





Warning 

To avoid confusion and any unintentional loss of the text in your text 
buffer, be careful when typing more than one command on the command 
line. Whenever you type the Add, Delete, Insert, Copy, or Replace 
commands, the relative line numbers of all subsequent text lines may be 
changed. The Editor uses these new relative line numbers when executing 
any subsequent commands. The Editor performs each command in turn, 
unless an error occurs while performing one of them, or unless you call the 
Assembler. A failure to locate the target of a character or string search is 
not considered an error. 


To ensure that you do not unintentionally delete text from your file, always 
check the relative line number of any text line before you replace or delete 
it. Do not type more than one command on the command line when using 
the Replace or Delete commands. 








Getting Help 


When you are first learning to use the Editor, you may find it 
difficult to remember all the Editor commands and syntax. The 
Editor gives you a reference card to help remind you of these 
commands and their syntax. 


To view this aid, type a question mark 


The Editor 


The Set Lowercase command 
activates the keyboard shift-key for the 
Apple |! or Apple || Plus. 


The Set Uppercase command 
deactivates your keyboard shift-key 
after you have activated it with the Set 
Lowercase command. 





following the colon prompt and press (RETURN). The Editor 
displays a table on the screen showing all the Editor commands 
and the common syntax for each. This table is longer than a full 
screen; to see the rest of the table, press or or 
any character key. 





Typing Uppercase and Lowercase Characters 


If you want to insert lowercase characters in your text (for example, 
you may want your program to display a message in uppercase 
and lowercase), type lowercase characters using the most 
convenient method for your particular Apple || system. 


è if you have an Apple lle computer, or if you have an Apple I! or 
Apple || Plus computer with the one-wire shift-key modification 
installed, and an ALS Smarterm 80-column display card in slot 
3: enter lowercase characters using your Apple II's lowercase 
input facilities. 


e if you have an Apple II or Apple II Plus computer, with the one- 
wire shift-key modification installed, but you do not have the 
ALS Smarterm 80-column display card: activate your keyboard 
shift-key by typing 


SET Lease 
and pressing (RETURN). 


After you turn on this lowercase character capability, you can 
return to uppercase character entry by typing 


SET Ucase 


and pressing (RETURN). You cannot type lowercase characters until 
you again type a Set Lowercase command. 


è if your Apple II or Apple |i Plus computer does not have a 
keyboard shift-key modification to allow you to type lowercase 
characters, you can use the Editor's control-character 
command to act as a software shift key. When you 
first start the Editor, the Editor sets the keyboard in caps lock 
mode. To unlock the keyboard and enable lowercase character 
entry, press (CONTROL)-(E) and then press (RETURN). To reenter 
caps lock mode, press (CONTROL)-(W) and then (RETURN). 


Remember: Whenever you are entering lowercase characters, you 
should remember that, although the Editor recognizes commands 
typed in either uppercase or lowercase, filenames and character 
Strings are all sensitive to case. This means that EditA and edita are 
recognized as two different filenames under DOS 3.3 and are seen as 
two different strings when the Editor is searching following a Find, 
Change, or Edit command. 
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DOS commands must be preceded by a 
period (.). 


The Editor does not work on random- 
access text files. To edit BASIC 
programs with the Editor, see 
Appendix F. 
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Executing Direct DOS Commands 


Any time you are using the Editor, you can perform regular DOS 
file-handling functions without leaving the Editor command level. 
This means you can manipulate disk files using the familiar DOS 
file commands. Only use direct DOS commands from the Editor to 
perform the following functions: 


èe Rename a file (RENAME) 

è Delete a file (DELETE) 

è Lock a file (LOCK) 

@ Unlock a file (UNLOCK) 

èe Obtain a file catalog (CATALOG) 

è Turn on the Monitor (MON) 

è Disable the MON command (NOMON). 

To execute a DOS command from the Editor command level, type 
a period (.) as the first character on the Editor command line, 


followed by the DOS command exactly as you would type the 
command in Applesoft or Integer BASIC. 


For example, if you type the command 
IRENAME PHOME LIST, OIFECTOR’', D2 


you command DOS to rename a file on a disk in drive 2. You must 
supply the slot and drive parameters when you type a direct DOS 
command; direct DOS commands do not use nor do they alter the 
Editor’s current slot and drive settings. 


Warning 

Using any DOS commands other than RENAME, DELETE, LOCK, 
UNLOCK, CATALOG, MON, and NOMON from within the Editor may 
destroy your text in the Editor's text buffer. For this reason, you should be 
very careful when using any direct DOS commands to avoid typing a DOS 
command that will destroy any text in memory. 





Saving and Retrieving Files on a Disk 


The Editor allows you to save and retrieve text files to and from a 
disk. The Editor can work with any DOS sequential text file, and is 
not limited to assembly-language program source files. Thus the 
Editor can be used to create and modify EXEC files and to 
examine and modify sequential data files written by BASIC 
programs, if these files will fit in the Editor’s buffer space. 


The Editor 








Volume 0 is a wildcard representing 
any volume. 


In this manual square brackets [] 
indicate optional command 
parameters. 


The Current Disk 


The Editor remembers the last disk slot, drive, and volume that you 
referenced when you are using the Editor, much as does DOS. 
When you load a file from a disk or save a file to a disk, the Editor 
sets its current disk slot, drive, and volume to refer to the disk slot, 
drive, and volume that you just used. When you first enter the 
Editor, the Editor's current settings are the boot slot, drive 1, and 
Volume 0. 


The Editor also remembers the filename that you used when you 
last loaded or saved your file. This filename is called the current 
filename, and is used by the Editor to save you from having to 
retype the filename every time you want to back up your file. 


To view the Editor's current filename, slot, drive, and volume, type 
wres 


and press (RETURN). Use the File command to display the current 
file name, slot, drive, and volume information, plus the current 
length of the text and the amount of space (in bytes) remaining in 
the buffer. 


If you have not yet executed a Load or Save command during an 
edit session, there is no current filename associated with your text. 
The Editor will display the slot, drive, volume, and length 
information in any case. 


To learn the amount of memory used by your text and the amount 
of unused memory, type 


LEHMa th 


and press (RETURN). Use the Length command to display the size of 
the text in the current text buffer and the amount of memory 
remaining, in bytes (characters). The sum of these two numbers is 
the total memory available to the Editor at the current time. 


When you type a file command to the Editor, you can specify a slot, 
drive, and volume after the filename just as you do under DOS. If 
you do not specify a slot, drive, or volume, the Editor searches for 
the file using the Editor's current slot, drive, and volume settings. 
In the discussions that follow, square brackets [] are used to 
indicate optional command parameters. 
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Use the Load command to load a text 
file from a disk into the text buffer. 


Error messages: see Appendix D. 


Use the Append command to append a 
text file from a disk to the end of your 
text in the text buffer. 


Loading a File 
To load a text file that is stored on a disk, type 
LOAD filename C.S5nJ C,0n] -C,nJ 


and press (RETURN). The Editor loads the text file that you specify 
into the Editor’s text buffer. Any text previously in the buffer is 
erased. After the Editor loads the text file, you can edit the file 
using any of the editing commands. 


If the Editor does not find the file you specified, the Editor displays 
the familiar DOS FILE HOT FOLIHOD message. Other error 
messages that may appear are discussed in the Appendixes. 


Appending Files 

You can put two or more text files together by using the Editor 
Append command. To copy a text file onto the end of the text that 
you are Currently editing, type 


APPEND filename C,Smn]J C,0nJ C, Yn] 


and press (RETURN). The Editor loads the specified text file from the 
disk and adds it to the text buffer at the end of your existing text. 
This command does not affect the Editor’s current filename, which 
remains as the filename used in the previous Load command. 


To insert a file of text into the middle of the text you are editing, 
you must type three commands: 


è First append the text file to the end of your existing text using 
the Append command. 


è Then use the Copy and Delete commands to move the text 
wherever you want within the text buffer. The Copy and Delete 
commands are discussed later. 


You can append a text file after a particular line in your program, 
replacing any text that currently follows this line with the text from 
the appended file. To do this, type 


AFFEHC line# filename C.,Sn] C.0nJ C.MrJ 
and press (RETURN). The Editor first deletes all the lines in the text 
buffer following the line number (line#) that you specify and then 


loads the specified text file into the text buffer following your 
existing text. 


The Editor 
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Use the Save command to store the 
contents of the text buffer in a disk file. 


File command: see the section “The 
Current Disk.” 


If the disk you specify is write- 
protected, or if no space remains for 
your file, the Editor displays the DOS 
error message. Other error messages 
may appear: see Appendix D. 





Saving Your Edited Files 


When you finish editing your text, you should save your file on a 
disk. As you are editing your text, you should also save it 
occasionally. To save the contents of the text buffer, type 


SAVE Cfilename] C, SnJ C. 0nJ C, Yn] 


and press (RETURN). This Save command lets you write the 
contents of the text buffer into a text file using the filename, slot, 
drive, and volume that you specify. 


lf you do not specify a filename, or if you don't specify a slot, drive, 
or volume, the Editor will save the text buffer using its current 
filename, slot, drive, or volume settings. For example, if you are 
saving a file with the same filename you used with the most recent 
Load command, you need only type 


SAVE 


and the Editor saves the text buffer, replacing the original file on 
the disk. 


If you type a Save command without previously specifying a 
filename with a Load or Save command, the Editor displays the 
current slot, drive, volume, and length information. At any time, 
you can find the filename that you used with the most recent Load 
or Save command by using the File command. 


Warning 

Typing the Save command causes the Editor to write over any file on the 
selected disk that has the same name as the file you are saving. The Editor 
does not prompt you when this occurs. To protect your other files from 
accidentally being overwritten, you should use the direct DOS LICH 


Editor/Assembler. If you have used the Lock command to lock all the text 
files on a disk and only unlock the file you wish to edit, you cannot 
accidentally overwrite a file if you should misspell a filename when typing 
the Save command. (This can easily happen when you are working with 
multiple source files whose names differ only slightly.) 


When the Editor overwrites a file with the same name as the text you are 
saving, the Editor does not delete the original file before overwriting it. 
This means that if the text you are saving is shorter than the original file on 
disk, the disk space allocated for the original file is not released for other 
uses. To conserve disk space, type a direct DOS .CELETE filename 
command before using the Save command. 


Do not issue a direct DOS . 3AE command in place of the Editor Save 
command. The DOS command causes DOS to save the contents of the 
current BASIC program. Since there is no such program, this command 
has unpredictable results. 
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The Editor's CAT command is a short 
form of the DOS CATALOG command. 
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Be Careful: While editing, back up your work every twenty minutes or 
so by saving the text buffer to your disk. Don’t get so busy editing that 
you forget. Although the chances of accidentally losing data are slight, 
a one-second loss of power to the computer can wipe out hours of 
editing. It is possible to lose your only copy of a file, or an entire disk, if 
a power loss occurs while you are saving to your disk. You can protect 
yourself against this type of loss by alternately saving your program to 
at least two disks. 


Viewing the Disk Contents 


Whenever you are using the Editor, you can view the contents of a 
disk by typing 


EM alog C,.5ni C.0nld C, Vn] 


and pressing (RETURN). This is equivalent to typing the DOS 
.CATALOG command 


CATALOG C.SnhnJ C,0nd Curd 


The rnain difference is that you can abbreviate the Editor 
command to the shorter HT to save typing. The direct DOS 
CATALOG command lets you catalog disks on other drives 
without altering the Editor's current slot, drive, and volume 
settings. 


Changing the Editor’s Current Disk 


The Editor has three commands that let you change the Editor’s 
current slot, drive, and volume settings. However, since you can 
just as easily specify a slot, drive, and/or volume when you type the 
Load, Append, Save, or Cat commands, you probably will not use 
these three commands often. 


To change the currently-selected disk slot, type 
SLat slat# 


and press (RETURN). The Slot command selects the slot number 
that the Editor will use in subsequent file Load, Append, Save, and 
Cat commands. The slot number (slot#) must be a number 
between 1 and 7 and this slot must contain a disk controller card. 


To change the currently-selected disk drive, type 
UR iwe drive 


and press (RETURN). The Drive command selects the current disk 
drive from which Editor will read or write text files. The drive 
number (drive#) must be either 1 or 2; if you select any other value, 
the Editor displays an error message. 
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Use the Add command to enter Input 
mode so that you can add lines of text 
to the text buffer. 





To change the currently-selected disk volume, type 
Wol wolF 


and press (RETURN). The Volume command selects the volume 
number of the disk from which the Editor will read or write text 
files. A volume number is required only when your system has a 
large number of volumes and uses the virtual volume mechanism 
that is typically used with large disk storage devices. If you are 
using only Disk II drives, you need not specify a volume number to 
read from or write to a file on a disk. 





Manipulating Lines in the Text Buffer 


The Editor accepts a number of commands to support adding, 
deleting, copying, inserting, and replacing lines witQin the text 
buffer. 


Adding Lines 

To add lines to the text buffer, type 
Add Cline#] 

and press (RETURN). 


You use the Add command to add new lines to the end of the text 
buffer or to add lines after a specified line number. If you type A, 
AC, or ACC and do not specify a line number, the Editor displays 
the number of the next line to be added to the end of the buffer 
and places you in Input mode. 


When you are in Input mode, the Editor accepts anything you type 
and inserts it into the text buffer. You can type any number of lines 
into the buffer, terminating each line by pressing (RETURN). After 
you press each (RETURN), the next line number is displayed. 


After you type your last line of text, press (RETURN) to enter this 
line and then press either (CONTROL)-(0) or (CONTROL)-(Q). Press 
immediately after the next line number appears on the 
screen. This terminates Input mode and returns you to the Editor 
Command level. 


You can also use the Add command with a line number. When you 
do this, the Editor places you in Input mode, but any lines that you 
type are added just after the line with the relative line number that 
you specified. (The Insert command places any lines that you type 
before the line with the specified relative line number.) 
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The Insert command allows you to 
insert lines of text between existing text 
in the text buffer. 


(CONTROL )-(D } or (CONTROL)-(Q) 


terminates Input mode. 


The Delete command lets you delete 
lines of text from the text buffer. 


Reminder: In Input mode you can use all the normal input editing 
functions, including the arrow keys. You can type uppercase and 
lowercase characters, using the facilities of your particular Apple Il. If 
your Apple |i has the Autostart ROM, you can also use the additional 
features for cursor movement. 


Input mode allows you to place control characters into your text 
file. Be careful not to insert control characters into your assembly- 
language programs, because the Assembler does not accept 
control characters in assembly-language source files. When you 
are using Input mode, control characters in your text are not 
displayed. They are displayed in inverse video when you use the 
List command to list your text. 


Inserting Lines 


To insert lines in the text buffer before a particular line number, 
type 
Inzert line# 


and press (RETURN). Typing the Insert command places you in Input 
mode. Any lines that you type following this command are inserted 
into the text buffer just before the line with the relative line number 
that you specify. Typing IH=EFT 1 inserts lines before the first 
line in your text file. Typing INSERT Sor INSERT lineg, 
where line# is higher than the last line number in the text buffer, 
works the same as the Add command: the text that you type is 
added to the end of the buffer. 


You can terminate Input mode by pressing either (CONTROL)-(D) or 
(CONTROL )-(Q). Remember that when you insert lines into your text, 
the relative line numbers of all lines that follow these lines in the 
text buffer will be increased. Check the new relative line numbers 
before you do any further editing to these lines. 


Deleting Lines From the Buffer 
To delete lines from the text buffer type 
Delete beging C-end#I 


and press (RETURN). Typing the Delete command deletes all the 
lines starting with the line numbered (begin#) and ending with the 
line numbered (end#). The beginning line number must be 
separated from the ending line number by a dash (-). If you do not 
type a dash and an ending line number, the Editor deletes only the 
line numbered (begin#). 


The Editor 


The Replace command lets you replace 
a range of lines with new text. 


The Copy command lets you copy a 
range of lines from one location in the 
he text buffer to another. 








Remember: Each time you use the Delete command, the relative line 
numbers of all subsequent lines in the text buffer are decreased. 


Replacing Lines in the Text Buffer 
To replace several lines of text in the text buffer, type 
Replace beging C-end#I 


and press (RETURN). Typing the Replace command is the same as 
typing a Delete command followed by an Insert command starting 
at the first line number (begin#) that you specified. The Editor first 
deletes the lines in the range from (begin#) to (end#) and then 
enters Input mode, allowing you to insert any number of lines to 
replace those that you deleted. You can insert lines exactly as you 
would after typing an Insert command. You must terminate input 


with (CONTROL)-(Q) or (CONTROL )-(0). 


Copying and Moving Lines 
To copy lines from one part of the text buffer to another, type 
TIe begin C-end#] TO dest# 


and press (RETURN). When you use the Copy command, the Editor 
copies the lines from (begin#) to (end#) and inserts them just 
before the line numbered (dest#) in the file. If you do not specify 
(end#), only the line numbered (begin#) is copied. When you type 
an ending line number (end), it must be greater than or equal to 
(begin). You must type the word TO before typing the destination 
line number, which must be outside the (begin+-end+) range. 


To move lines from one part of the text buffer to another, you must 
use two commands. First, use the Copy command to move the 
Original lines to their new location. Then use the Delete command 
to remove the lines from their old location. 


Renumbered Lines: Remember that when you copy lines to a new 
location, the relative line numbers of all text lines following that 
location will change. This means that when you copy lines to a (dest#) 
less than (begin#), the relative line numbers of the original lines will 
change when the copied lines are inserted before them. Before you 
delete the original lines, check their new relative line numbers because 
they change also. 
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Use the New command to clear the text 
buffer. 


Test-buffer pointers: see Appendix H. 


Use the List command to display lines 
of text with relative line numbers. 
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Clearing the Text Buffer 
To clear all of your text from the text buffer, type 
HEH 


and press (RETURN). Typing this command lets you clear the current 
text buffer, in effect deleting all of your text from the buffer. You 
use this command to clear the buffer before typing a new text file 
or in conjunction with the Swap command. 


If you want to save the text in the text buffer, use the Editor’s Save 
command. When you type the New command, the Editor does not 
prompt you to save your work before it clears the text buffer. 


To Recover: If you accidentally clear a text buffer, you can possibly 

restore the buffer by using the Monitor commands. The New command 

merely resets an end-of-text pointer and does not destroy the contents 

of the buffer. Using the Monitor, you may be able to determine the 

previous end-of-text address and then set the end-of-text pointer to 

this address. The three text-buffer pointers in the Editor are defined ir: 
Appendix H. = 





Viewing Your Text in the Text Buffer 
The Editor lets you view the text in the text buffer in two different 
ways: 


@ with the relative line numbers normally displayed, and the 
control characters displayed in inverse video. (Use the List 
command.) 


@ without relative line numbers, and the control characters sent 
as control characters to the video display or to a printer. (Use 
the Print command.) 


Listing Lines of Text 
To display lines of text from the text buffer, type 
Litt Chegin# C-end#II 


and press (RETURN). The List command lets you display lines of text 
on the screen, and shows the relative line number before each line. 


è if you do not specify any line numbers with the List command, 
the Editor lists the contents of the entire text buffer. 


è |f you specify a beginning line number (begin#), the Editor 
begins listing from that line. Otherwise the Editor starts listing 
lines from the beginning of the text buffer. If the beginning line 
number is the only number that you specify, the Editor lists only 
that line. 
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Press (CONTROL)-(R ) to relist the lines 


ycu displayed with the previous List 
command. 





è |f you specify a beginning line number, a hyphen, and an ending 
line number (end#) larger than the beginning line number, the 
Editor lists only those lines in the range from the beginning line 
number to the ending line number. 


è |f you specify a beginning line number, a hyphen, and the 
number of lines you want to list (line count), where the count is 
smaller than the beginning line number, the Editor lists the 
counted number of lines starting with the beginning line 
number. 


è |f you specify a beginning line number, a hyphen, and no ending 
line number or line count, the Editor lists all lines from the 
beginning line number to the end of the text buffer. 


è |f you type more than one range of line numbers, separating 
each range with a comma, the Editor lists each range of lines 
and shows a blank line between each group of lines. 


You can interrupt the listing at any point by pressing (SPACE). To 
continue the listing, press any other key, except (CONTROL)-(C). If 
you press again, the Editor displays one line and stops. 
This allows you to step through the text buffer, examining one line 
at a time. You can cancel the listing at any time by pressing 
(CONTROL)-(C); the Editor will return to the command level. 


The Editor displays control characters as inverse-video characters 
on the screen when you use the List command. If your Apple |! 
system has lowercase display capabilities, lowercase characters 
display in lowercase. If your Apple II system does not have this 
capability, lowercase characters will appear as punctuation 
symbols on the screen. 


Relisting Lines of Text 


The Editor always remembers the line numbers that you specified 
with the most recent List command. To relist the lines displayed by 
the previous List command, press 


(CONTROL)-(R) 


and press (RETURN). This lets you display the lines of text as if you 
completely retyped the previous List command using the same 
relative line numbers. If you have added or removed lines of text, 
the Editor may not list the text that you intended. 
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Use the Print command to display lines 
of text without showing line numbers. 
This command can also be used to 
obtain a printed copy of your file. 


The DOS .PR# command can be used 
to turn a printer on or off from within the 
Editor. 


Printing Lines of Text 


To display or print lines of text without relative line numbers, type 
Frint Chegin# C-end#]] 


and press (RETURN). Typing this command displays the indicated 
text without showing line numbers. This command differs from the 
List command in two respects: 


è Relative line numbers are not printed. The first character of 
each line is printed in column 1. 


The control characters that the Editor displays in inverse video 
when you use the List command are sent to the screen or printer 
as control characters. This lets you insert control characters in a 
file to activate any printer-control features that you may have in 
your printer. 


Activating a Printer 


To activate a printer from the Editor, you must use the direct DOS 
command facility: for example, if your system uses a printer 
interface card, type 


PR# slat# 


and press (RETURN). (slot#) is the number of the slot containing the 
printer interface card. Once you activate your printer, you can use 
the Editor List or Print commands to print the current contents of 
the text buffer. 





Warning 
Never specify . FF # =. Slot 6 contains the disk controller card. 








Changing Text Within a Line 


This section describes the commands you use to find and revise 
text lines that are already in the text buffer. These commands are 
Find, Change, and Edit. 


The Editor 


Use the Find command to search the 
text buffer for occurrences of particular 
words or character strings. 


(CONTROL )-(A) in a search string is a 


wildcard that matches any character. 





Searching Text 


To search through the text for the occurrence of a particular word 
Or string, type 


Find Chegin#C-end#J] ¿str Lrg: , 


and press (RETURN). <string> is the word or character String that 
you want to search for. This search String must be enclosed by two 
delimiting characters that do not occur in the String itself. The 
delimiters are shown above as period characters. In place of the 
periods, you can also use quotes, Slashes, or any punctuation 
character other than a dash or a comma. 


Notice: Characters enclosed within brackets, such as <charstr> 
indicate a character string. When you type a string, do not type the 
brackets. 


The Find command lets you locate and list all lines containing the 
specified search string that fall in the range of relative line 
numbers from (begin) to (end+#). If you do not specify beginning 
and ending line numbers, the Editor searches the entire text 
buffer. The Editor lists a line only once regardless of how many 
times the string occurs within that line. 


You can specify a wildcard character within the search string by 
pressing (CONTROL)-(A). A (CONTROL)-(A) in the string represents 
any character, allowing you to search for all sets of similar 
character strings that may differ in one or more characters. 


For example, if you type the command 
Pen LEST. 


where the * represents a wildcard, and then press (RETURN), the 
Editor searches your entire text and lists any lines where the 
character sequence TEST is followed by another character. Any 
lines containing TEST1, TESTX, or other TEST" sequences are 
found and listed. 


Remember: in this Editor when you press (SPACE), it will print as a tab. 
This is convenient when you are editing a source program and 
searching for a specific text line. Instead of the Space character, you 


can use (A) (the wildcard character) for this purpose. 
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Use the Change command to replace 
occurrences of a word or String with 
another word or String. 


Changing Text 


To substitute a new character String for some or all occurrences of 
an old character String in the text buffer, type the command 
Change Cb 23 1né#C-end#I]] , o ldstr?, Cnewstr 


and press (RETURN). The Change command lets yOu search the text 
buffer for occurrences of the search String <oldstr> and replace 
(at your option) any occurrence that it finds with the new string 
<newstr>. You can use any punctuation character except a dash 
or a comma as the delimiter instead of the period shown above. 


If you want to search a range of lines and you specify a beginning 
line number ( begin#) other than the first line of the text buffer, the 
search begins from that line. If you type a dash and an ending line 
number (end#) after the beginning line number, the Editor 


ending line number. If you omit the dash, then the Editor only 
searches the line with the relative line number (begin). 


Whenever you type the Change command, this question appears 
ALL OF SOMES As a9 


You can indicate that you wish to change all occurrences of the 
search string in the lines that you specified (type (A)), or that you 


If you respond with (S), the Editor searches for the first 


If you respond by typing either uppercase or lowercase (Y), the 
Editor replaces the Original line in the file with the displayed line 
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By the Way: If you reject a specific change by typing either uppercase 
or lowercase (N), the Editor does not redisplay the text line in its 
original unchanged form. The actual text in the text buffer remains 
unchanged. 


When you specify the search string <oldstr>, it must contain at 
least one character. You can use an empty string <newstr> to 
remove occurrences of text from your file. For example, the 
command =, JIJHE ,, removes all occurrences of the string JUNK 
from the text buffer (that is, replaces these occurrences with 
nothing). 


You can omit the trailing delimiter following the new string, since 
pressing signals an end of the string. You cannot use the 
command delimiter as a delimiter in your search strings. 


As with the Find command, you can use the wildcard character 
(CONTROL)-(A) in your search string to represent any character. 
Using the wildcard, you can change a set of similar character 
strings into the same identical new string. If you type 
(CONTROL)-(A) in the new string <newstr>, it is simply entered into 
your text as a (CONTROL)-(A) Character. 


Changing the Command Delimiter 


The Editor recognizes the colon as a command delimiter to 
separate commands. You cannot use a colon in a search string, 
unless you first change the Editor's command delimiter to some 
other character. Since the colon is not commonly used in 
assembly-language programs, you probably will not have to 
change the command delimiter often when you are editing your 
source programs. 


To change the Editor's command delimiter, type 
SET Delim . trew cmg delimiter 


and press (RETURN). The Editor's command delimiter becomes the 
character that you enclose within the delimiters (periods) in tne 
command above. 


A command delimiter cannot be a space character. If you set the 
new command delimiter to a space character or simply type ETC 
and press (RETURN), the system just prints the current command 
delimiter and returns to the command level. Do not use a period as 
the command delimiter, since this is the Direct DOS Command 
character. The Editor accepts any other printing character (except 
(RETURN)) as the command delimiter. 
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Use the Edit command to enter edit 
mode; you can then change any 
characters in the text buffer. 


Entering Edit Mode 


The Change command is useful for making identical changes to 
several different lines of text. To make individual changes that will 
be different for each line, you will want to use the Editor’s Edit 
mode. For example, if you entered some assembler source lines 
without comments, you might want to go back and add individual 
comments to a group of lines or to all the lines containing a 
specific identifier. 


To enter Edit mode, type 
Edit Chegin# C-end#IJIC. <etrina?. J 


and press (RETURN). When you type the Edit command, you enter 
Edit mode and see on the screen the first line that you specify. 


When you type the Edit command, you must specify the lines that 
you want to edit: 


è |f you omit both the optional line numbers and the optional 
search string, you can edit all the lines in the text buffer. 3 


e |f you specify a line number or a range of line numbers (begin#- 
end#), you can edit each of the lines in this range, one after 
another. 


e |f you type both a range of line numbers and a search string, or 
just a search string, you can edit only those lines in the range of 
line numbers that contain an occurrence of the search string. 
You can also use the wildcard character ((CONTROL)-(A)}) in the 
search string. 


Character Editing Using Edit Mode 


Once you are in Edit Mode, you see the next line that you can edit, 
with the inverse-video cursor on the first character in the line. 
Using the arrow keys, you can move the cursor to the left or right 
along the line. Using other control characters, you can replace, 
insert, or delete characters from the line and immediately see your 
changes on the screen. The resulting line may be either shorter or 
longer than the original line. 


After you use the arrow keys to place the inverse-video cursor over 
a character that you wish to edit, you can 


e replace the character by typing a new character over the old 
character; 


è delete the character by pressing (CONTROL)-(0); 
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In Edit mode use (CONTROL)-(V) to 


enter a control character. Control 
characters are displayed in inverse 
video. 


In Edit mode, (CONTROL)-(F) finds a 


specified character on the line you are 
editing. 


-(R) restores an altered 
line to its original form. 





è insert additional characters before the current character by 


Pressing (CONTROL)-(7) and typing the additional characters. 
End the insertion by pressing an arrow key, any control 


character other than (CONTROL)-(V), or Pressing (RETURN). 


If you want to enter a control character in the line that you are 
editing, precede this control character by (CONTROL)-(V) 
(Verbatim). You can use this (CONTROL)-(V) sequence either to 
replace or insert control characters in the line. if you type any 
nonediting control character without first preceding it with 


(CONTROL)-(V), your Apple II beeps. 


Control characters are always displayed in inverse video so they 
Stand out on the screen. You should not use control characters in 
your files, since the Assembler does not accept control characters 
in assembly-!anguage source files. 


You can type lowercase characters if you enable this feature before 
you enter Edit mode. If your Particular system requires them, 
(CONTROL)-(E) and (CONTROL)-(W) work as the normal 
Enable/Disable Lowercase commands. If you have lowercase 
characters in your text, these characters will appear as blinking 
inverse-video uppercase characters when you place the cursor 
over them in Edit mode. This does not mean that these characters 
are changed in your text buffer; they will appear normally as soon 
aS you move the cursor to another character. 


When you position the cursor Over a tab character (Normally 
(SPACE)), the cursor jumps over the empty space caused by the tab 
character. If you are inserting characters before a tab character, 
this empty space gradually fills in as you type more characters. If 
you replace the tab character with another character, the line on 
the screen may appear to jump to the left as the tab’s empty space 
is eliminated. 


You can jump quickly within the line you are editing when you use 
the Edit mode character-search command: (CONTROL)-(F) followed 
by a character moves the cursor to the first occurrence of that 
character to the right of the Original cursor position. If the 
indicated character does not occur on the edit line, the cursor 
remains in its original location. 


You can restore altered characters on the edit line. Press 


(CONTROL)-(R) at any time to restore the line to its original form: this 


lets you re-edit the line from scratch. 
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Use (CONTROL)-(T ) to save only the 


first part of an edited line. 


Use (CONTROL )-(X } at any time to 


cancel Edit mode and return to the 
Editor command level. 


Table 2-1. Edit Mode Keystroke 
Summary 


When you are satisfied with an edited line as displayed on the 
screen, press (RETURN). This places that line back in the text buffer 
and presents the next line for editing. When you indicate, by 
pressing (RETURN), that you are through editing all the lines that you 
specifed in the Edit command, you return to the Editor command 
level. 


if you inserted some text and want to save only the first part of the 
line that you edited, place the cursor to the right of the text that 
you want to save, and press (CONTROL)-(T ) to truncate the line. 
Only the text to the left of the cursor is placed in the text buffer. 
The next line then appears for editing. 


If you want to cancel Edit mode at any time and return immediately 
to the Editor command level, press (CONTROL)-(x). This leaves the 
current line in its original form in the text buffer and returns you to 
the command level. If you changed the line displayed on the 
screen, that line in the text buffer remains unchanged but the line 
displayed on the screen is not restored to its original form. 


Table 2-1 gives a summary of the Edit mode keystroke commands. 





Editing Function Edit Mode Keystroke 

Move cursor left one character 

Move cursor right one character (—) 

Delete current character (CONTROL)-(D ) 

Insert characters at this position (CONTROL)-(7 ) 

Replace a character any noncontrol character 
Enter control character into text (CONTROL)-(V ) any character 
(Verbatim) 

Restore the original line (CONTROL)-(R) 


Find the indicated character in the line | (CONTROL)-(F ) any character 


and move the cursor there 


Store line as it appears on screen RETURN 
Truncate at current cursor and store CONTROL 


text in text buffer 


Cancel Edit mode and return to CONTROL )-(X< ) 


command level 
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The Swap command allows you to edit 
two files (in separate text buffers) at 
once, letting you jump back and forth 
between the two buffers. 


The ASM command is discussed in 
Chapter 3. 








Editing Two Files at Once 


Often when you are editing assembly-langquage source files, you 
may want to check the contents of another source file, or to make 
changes to another file, without saving and reloading your current 
editing file. The Editor lets you edit two files at once by splitting the 
text buffer into two parts. If there is sufficient room in the two 
resulting buffers, you can then edit the two text files concurrently, 
alternating between the two buffers by using the Swap command. 


This feature is useful if you are working on an assembly program 
that spans multiple files. Very often, you want to reference quickly 
other files that are also in the source program to make corrections 
and to incorporate changes. 


lf you are currently editing one text file and want to edit a second 
one concurrently, type 


SWAP 
and press (RETURN). This splits the current text buffer and stores 
the current filename, slot, drive, volume, and file size in memory. 
The original text buffer is split at the end of the current text and 


becomes text buffer +1. Text buffer +2, which is empty, becomes 
the current text buffer. 


You can now load, edit, list, save, or perform any other editing 
operations on the contents of text buffer +2, while text buffer =1 
remains in memory. If you want to go back to the text in text 
buffer +1, just type 


SMA 


and press (RETURN) a second time. The Editor then makes text 
buffer +1 the current text buffer, and preserves the contents of 
text buffer #2. 


While you have two text buffers in memory, you can perform any 
editing function. You can identify which text buffer you are 
currently editing by the buffer number, either 1 or 2, that appears 
before the command prompt on every command line. 


You cannot call the Assembler using the ASM command while you 
have a second text buffer active. If you try to do so, the screen 
displays MULTI BUFFER ERROR. You cannot call the Assembler 
until you deactivate text buffer #2. 
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The KILL2 command deactivates text 
buffer =2, and clears any text that was 
in this buffer. 


The Tabs command lets you change the 
tab settings in effect when you begin 
using the Editor program. 
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To deactivate text buffer #2 and delete any information that is in it, 
type 
RILL 


and press (RETURN). If you wish to save the contents of this buffer, 
you should do so by typing the Save command while you are 
currently editing text buffer #2. You can type the Kill2 command 
while you are editing either text buffer. 


As an alternative, if you wish to transfer the contents of text 
buffer #2 into text buffer +1 and then deactivate split-buffer 
mode, you can do so by typing the New command while you are 
currently editing text buffer +1. This command clears the contents 
of text buffer +1. Then to activate the contents of text buffer #2, 
type the Swap command. If text buffer +1 is empty when you type 
this Swap command, split-buffer mode becomes inactive and the 
old contents of text buffer +2 become the new contents of the 
single remaining text buffer. 





Altering the Display 


The commands discussed in this section control various display 
features of the Editor. None of these commands alter the contents 
of the text buffer in any way. 


Setting Tabs 


When you first run the Editor program, the standard tab positions 
for formatting the appearance of 6502 assembly-language source 
files are in effect. Initially, the space character is used as the tab 
character, and the tab columns are set at 16, 22, and 36. If you are 
using the Editor to create other types of text files, you probably 
want to change these tab settings and the tab character. 


To change the tab settings, type 


Fase L tabcol C., tabcol £.tabeol C... 77337 
C w<tabchar>. J 


and press (RETURN). You can specify up to ten tab positions 
following the Tabs command, separating each tab position with a 
comma. You must type these positions in increasing order for 
them to function properly. If you type a delimiter (shown as a 
period above) followed by a different single character and the 
delimiter, this single character becomes the new tab character. If 
you type the Tabs command without any parameters, you turn off 
the tabbing function. 
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Use only (SPACE) or (CONTROL)-(1 ) 


as the tab character when you are 
editing assembly-lanquage source files. 


You can change the tab character to any character that you like. If 
you are editing assembly-language source files, you must use 
either the space character or (CONTROL)-(/ ) as the tab character. If 
yOu are using an Apple lle system, functions the same as 
pressing (CONTROL)-(1 ). The Assembler recognizes only these two 
characters as valid tab characters. 


The Editor recognizes tab characters only in the first 40 columns of 
each text line. If you set any tab positions beyond column 39, these 
tab positions are ignored by the Editor, although the Assembler 
will still use these tabs to arrange its output listings. 


The Editor uses the tab positions when text lines are displayed in 
response to a List, Print, or Edit command. Tabs are not active 
when you are in Input mode: when you type a space, it appears as a 
single space. When you later list this line, the space is treated as a 
tab character and may be displayed as several blanks on the 
screen. 


Tabs also cause a slightly different appearance for lines when you 
print rather than list them, since a six-column relative line number 
is not displayed when you print lines. Under most conditions, the 
same line appears with six extra spaces between the first two fields 
when you use the Print rather than the List command. 


Using a 40- or 80-Column Display 


If you have an Apple lle with the Apple Ile 80-Column Text Card, or 
an Apple || or Apple |i Plus with an ALS Smarterm 80-Column 
Card in slot 3, then the Editor automatically comes up in 80- 
column uppercase and lowercase display mode. If you wish to 
alternate between 80-column and 40-column display modes, you 
type 

Olina 48 


and press to enter 40-column mode, and you type 


CaL umn Se 


and press to return to 80-column mode. If your Apple II 
system does not have 80-column display capability, these 
commands are ignored. 
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Use the Truncate-on command to see 
only the first 40 characters of each text 
line when listing or printing lines. 


The Truncate-off command 
deactivates an earlier Truncate-on 
command. 


The End command lets you leave the 
Editor and return to Applesoft BASIC. 


Truncating the Display 


lf you are using a 40-column display to create assembly-language 
source files, you can selectively list or print only the first three 
fields of your source statements, truncating the comment field so 
that each statement can be displayed only on a 40-character line. 
When you type 


TRurecoh 


and press (RETURN), from that point onward you see only the 
characters in your source statements up to the first space- 
semicolon sequence in the line. This two-character sequence is 
how all 6502 comments begin when you include them at the end of 
your source lines. Since these comments typically wrap to a 
second line when you use 40-column display mode, you can make 
your source programs much easier to read by using the Truncate- 
on command. This command in no way affects the actual text in 
the text buffer; it only affects what you see on the screen when you > 
type a List or Print command. This feature does not affect the 
operation of the Find, Change, or Edit commands. 


To restore the Editor to its normal display mode, type 
TRurcorr 
and press (RETURN). This turns off the line-truncation feature that 


you earlier activated with the Truncate-on command. 


Truncation-on mode is automatically suspended when you are 
using Edit mode so you will not accidentally lose your comments 
because they are not displayed. 





Leaving the Editor and Returning to BASIC 


When you finish editing a program and have saved your work, you 
can return to the BASIC command level (immediate mode) by 
typing 

EHC 


and pressing (RETURN). When you type the End command, the 
Editor simply returns to BASIC; none of the text that you have 
been editing is saved or altered. 


Warning 

The Editor does not automatically save your work; you must use the Save 
command before you leave the Editor if you want to preserve the program 
you have been editing. 
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The Monitor-on command lets you 


leave the Editor and enter the Apple |! 


= 
+ 


Monitor. Typing 2040 or 
(CONTROL tea returns you to the 


Editor. 


Memory areas used by the 
Editor/Assembler: see Appendix H. 


A 





If you type the End command by accident, you can usually recover 
the work you were editing. Immediately type after the BASIC 
prompt 


MASFILES S 
and press (RETUAN). Then type 


CALL 3675 


and press (RETURN). You are now at the Editor command level. 


ie amma 


Warning 

When you return to the Editor, examine your edit file completely. Do not 
save this edited file until you are sure that it is intact, or you might replace 
the intact old version of your file on a disk with a scrambled new version. 


Entering the Monitor 
You can leave the Editor and enter the Monitor by typing 
Mor 


and pressing (RETUAN). Normally you do not use this command 
unless you want to use one of the Monitor commands. To return to 
the Editor command level from the Monitor, type 2046 or 


(CONTROL)-(Y). If you have an 80-column display card installed, use 
3D0G. 


When you are in the Monitor, you can use any of the Monitor 
commands. If you expect to return to the Editor, you must not 
disturb any of the memory areas used by the Editor/Assembler 
system. 


7S neers a 


Warning 


Note that if you enter either BASIC from the Monitor, you will destroy 
memory areas used by the Editor/Assembler. The Monitor-on command 
is a tool for the experienced Apple programmer and would be better left 


unused by the beginner. 
eee eee 


Identifying the Absolute Location of Text in Memory 


To manipulate text from the text buffer using the Apple II Monitor. 
you may sometimes find it useful to know the absolute location of 
a particular text line in memory. To do this from the Editor 
command level, type 


Where lineg 
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and press (RETURN). You can use this command to display the 

absolute memory address of the first character of the indicated 
line of text. It also provides a means of discovering the current 
memory address of the beginning of the text buffer; to find this, 


type 
hier ie 1 

and press (RETURN). Normally, you see this display 
L=F2508 


which is the same as 10240 decimal, the normal starting location 
of the Editor's text buffer. 
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73 Giving Directions to the Assembler 
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Controlling the Overall Assembly 


ORG 
DSECT 
DEND 
OBJ 
REL 
SW 16 


Assigning Information 


EQU 

DEF or ENTRY 

ZDEF 

EXTRN or REF 

ZXTRN or ZREF 

A Note on External Symbols 


Generating Data in Your Object Code 


DFB or DB 
DW 

DDB 

DS 

MSB 

ASC 

STR 

DCI 

DATE 
IDNUM 


Controlling Conditional Assembly 


DO, IFXX, ELSE, and FIN 
FAIL 


Source File Directives 


CHN 

INCLUDE 

SBUFSIZ and IBUFSIZ 
MACLIB 


Controlling Your Assembly Listings 


PAGE 

LST 
Cycle Times 
Generated Object Code 
Warnings 
Unassembled Source 
Expanded Macro Source 
Alphabetic Symbol Table 
Value-Ordered Symbol Table 
Sixup Symbol Dump 
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95 CHR 
96 SKP 
96 SBTL 


96 Using Macros in Your Assembly- 
97 Calling Macros in Your Progra 
97 The Macro Definition File 
99 The &0 Parameter 

100 The &X Parameter 
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Appendix B contains a summary of the 
6502 assembly-language mnemonics, 
address-mode syntax, and assembly 
directives to use in assembly-language 
programs. 





The 6502 Assembler 


The 6502 Assembler in the Tool Kit Volume II is a powerful tool that 
lets you program your Apple |i system in assembly language. You 
use the Assembler to translate the assembly-language source files 
that you create using the Editor into executable object programs 
that will run on your Apple |i. The Assembler can also help you 
locate problems that may occur in your programs by generating 
assembly listings, error summaries, and symbol table listings to 
accompany your programs. 


This chapter tells how to use the Assembler, but does not describe 
how to program in 6502 assembly-language. Several excellent 
reference manuals on 6502 programming are listed in the Preface. 
You should be familiar with one of these books before you continue 
reading this chapter. 


è The first part of this chapter describes some of the 
characteristics of the Assembler. 


e A brief tutorial on using the Assembler follows. It leads you 
through an assembly of the program source file that you created 
as part of the Editor tutorial in Chapter 2. 


è The remainder of this chapter introduces the structure of the 
assembly-language source files that you use as input to the 
Assembler program. The syntax of assembly-language source 
statements and the various Assembler directives that you can 
use are all described in detail. 


Introduction to the Assembler 


The Assembler creates an executable object program by 
translating each of the assembly-language statements in your 
program source file into an executable machine operation code 
opcode. These assembly-language statements can include any of 
the standard 6502 assembly-language mnemonics and addressing 
syntax. 
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In addition, you can include an extensive set of Assembler 
directives, or instructions to the Assembler itself, in your program 
source file. The Assembler has a limited macro capability that you 
can use to make your programming more efficient. You can also 
chain several source files together to assemble modular or very 
large 6502 programs. All of these features are described in this 
chapter. 


The Assembler can create both binary object programs and 
relocatable object programs. Binary programs are programs that 
you can run directly using the DOS BRUN command. Relocatable 
programs are assembly-language programs that you can load and 
run during the execution of a BASIC program. Relocatable object 
programs are discussed later in this chapter and in the chapter on 
the Relocating Loader. 


A Tutorial: Using the Assembler 


This brief tutorial shows you how to assemble your assembly- 
language source file using the Assembler. When you finish with this ~ 
tutorial, you will have 


è assembled the assembly-language source file you created in the 
tutorial in Chapter 2; 


è stored the resulting binary program on a disk. 


To work through this tutorial, you need: 
è your Apple Il computer running the EDASM program 


è the TESTPROGRAM file that you created during the Editor 
tutorial in Chapter 2. 


You will use the Assembler to assemble the TESTPROGRAM 
source file you created using the Editor. The Assembler saves the 
assembled object program as a binary file on your disk using the 
name TESTPROGRAM.OB,JO. 


You will use this executable binary program when you work the 
Bugbyter tutorial in Chapter 4. For this reason, follow the steps in 
this tutorial, if only to prepare the necessary file you will use in the 
next tutorial. 





Getting Started 


The Assembler is an integral part of the combined 
Editor/Assembler program; you can call the Assembler only from 
the Editor command level. If your Apple II is not currently running 
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See the section "Getting Started" in 
the tutorial in Chapter 2 for a 
description of how to run the 
Editor/Assemblier and how to use the 
Editor command level. 


the Editor/Assembler, follow the Editor tutorial to start up the 
Editor/Assembler and place yourself in the Editor command level. 
When you see the colon (:) prompt character at the left margin of 
your screen, you are at the Editor command level. 


Make sure your assembly-language source program is on the DOS 
Programmmer’s Tool Kit Volume II disk. 





What You Do What Happens 

1. Type the Editor command The Editor displays the 
contents of the current disk, 

LAT which should contain your 
program as a text file named 

and press (RETURN). TESTPROGRAM. 





By the Way: If your program is not shown in the disk contents, check 
that you are reading the contents of the DOS Programmer's Tool Kit 
Volume Il disk. If your program is not on this disk, then perhaps you did 
not complete the Editor tutorial in Chapter 2. Return there now and 
complete the steps to create and store your assembly-langquage 
program on the disk. When you finish, return to this tutorial to 
assemble your program. 





Assembling Your Program 





Warning 

Since the Assembler overwrites the Editor’s text buffer as it assembles 
your program, you must save any edited text and clear the text buffer 
before you use the Assembler. (For an exception to this rule, see the 
section ‘‘Coresident Assembly With a 64K Apple |l" in this chapter.) The 
Save and New commands to do this are described in Chapter 2. If you do 
not clear the text buffer before calling the Assembler, you see a BIIFFEF 
EFFIIF message. 





When you have verified that your source program is on the proper 
disk, you can use the Assembler to assemble your program. 





1. From the Editor command The Assembler reads your 

level (the colon prompt), type program source file 
TESTPROGRAM from the 

ASM TESTFROGRAM current disk and assembles it to 
produce a binary file. The 

and press (RETURN). Assembler saves this binary file 


to the disk using the name 
TESTPROGRAM.OBJO. 
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If you are using an Apple || system 
without an 80-column text card, your 
screen shows only the first 40 columns 


of this listing. a 


See Appendix D for explanations of the 
error messages. 


The Assembler also generates a complete assembly listing of your 
program on your video screen. This assembly listing looks like this: 


SOURCE FILE: TESTPROGRAM 
--- NEXT OBJECT FILE NAME IS TESTPROGRAM. 0BJ8 
6: 1000 ORG 


166 1 $1000 
1000: A0 CA 2 START LOY #$CB 
1882:A2 86 3 LDX #0 

1004:20 ØD 18 4 LOOP JSR STORE 
1007 : E3 3 INX 

1009:E0 05 6 CPx #5 
196A:0@ FS 1004 rd BNE LOOP 
1860: 68 3 RTS 

100D : CS 9 STORE INY 

160E : 98 18 TYA 

100F:90 86 11 11 STA BUFF, x 
1012:60 12 RTS 

1813: YBED 13 DS $ED, $00 
1166; AHHA 14 BUFF OS 18, $48 
1100 BUFF 1004 LOOP 71000 START 


** SUCCESSFUL ASSEMBLY := NO ERRORS 

** ASSEMBLER CREATED ON 18-SEP-82 869820 
** TOTAL LINES ASSEMBLED 15 

*X FREE SPACE PAGE COUNT 79 


Didn’t Work? if you made any typing mistakes when you typed the ASM 
command, the Editor/Assembler displays an error message and 
returns you to the Editor command level. Just retype the ASM 
command correctly and try again. 


If the Assembler cannot find your TESTPROGRAM source file, use the 
Editor's Catalog command to verify that your file is on the disk in the 
currently-selected drive. 


If the Assembler found any errors in your TESTPROGRAM source file 
during its assembly, you probably made a typing mistake when you 
created this file. Go back to the Editor tutorial now and make sure that 
your file matches the text shown in the tutorial. If not, use the Editor to 
fix any mistakes before you try to assemble your program again. 


2. To verify that your binary The Editor shows the contents 

object file is stored on the disk, of your disk, with 

type TESTPROGRAM.OBJO shown 
CAT at the end of the other files on 
i the disk. 

and press (RETURN). 


DISK VOLUME 168 
A 864 HELLO 
: Ole « 


T 882 TESTPROGRAM 
B AAZ TESTPROGRAM. OBue 





The 6502 Assembler 


The current slot, drive and volume 
settings of the Editor are discussed in 
Chapter 2 in the section “The Current 
Disk.” 





You have now finished the Assembler tutorial. You iearned how to 
use the Assembler 


e to assemble your assembly-language source file and produce 
an executable binary object program, 


e to store the binary program onto a disk; 


è to generate an assembly listing of your program. 


The TESTPROGRAM.OBJO binary (B) file that you produced in this 
tutorial will be used in Chapter 4 as you learn how to test and 
debug your assembly-language programs. 


Using the Assembler 


The Assembler tutorial demonstrates a very simple use of the 
Assembler: to assemble your program source files from a disk and 
to store the resulting object program on a disk. This is probably 
the most common use of the Assembler. You can also use the 
Assembler in several other ways. In the sections that follow, each 
of these additional techniques is described in detail. 


i 


Calling the Assembler 


To call the Assembler from the Editor command level, type the 
ASM command using the following syntax: 


aah ercefile C.Cobsfiled E,ccSIsi Cc. COCOIds 


e The source filename (designated srcefile above) must be the 
name of a valid assembly-language source file in the Editor's 
current slot, drive, and volume. 


e You may also specify an object filename (designated objfile 
above), and an object file slot, drive, or volume. You need to 
specify this information only if you want the object file to be 
stored under a different name or on a different disk. 


e |f you do not specify an object filename, the Assembler creates 
an object filename by appending the characters . NEW to the 
source filename. If you do not specify an object file slot, drive, or 
volume, the Assembler stores the object file on the same disk 
from which it read your program source file. 


è if you specify a Volume parameter, the Assembler directs the 
object file to the disk bearing this volume number. If this volume 
is not present in a drive when the Assembler attempts to open 
the object file, the Assembler prompts you to insert this disk. If 
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you specified an incorrect volume number and the Assembler 
prompts you to insert an incorrect disk, press (CONTROL)-(C) to 
end the prompting and allow you to start again. 


Remember, the optional parameters are positional and must occur 
in the order shown. If you want to use the default values of some 
Parameters but specify one of the later ones, type a comma in 
place of each defaulted parameter. For example, if you want to 
specify only the drive of the object file and use the default object 
name and slot, then type this ASM command 


ASM PROGRAM, , 02 


Note that you must include commas in the ASM command to 
indicate the omitted object filename and disk slot parameters. The 
labels =, C, and '! are optional—the numbers themselves will 
suffice— but the labels make it easier to remember the purpose of 
each parameter. 


By the Way: If you have a 48K Apple || system, before you call the 
Assembler, make sure that the Editor/Assembler system disk is still in 
drive 1. The Editor has to load the Assembler program from the disk 
before it can assemble your program. 


lf you have an Apple |i system with 64K of memory or more, the 
Assembler program is always in memory when the Editor/Assembler 
program is running. It does not have to be loaded from the disk. 


Suppressing the Generation of Your Object File 


When you are assembling your program simply to get a listing or to 
check for errors, you can speed up the assembly process 
considerably by suppressing the generation of your object file on 
the disk. To select this assembly option, you must specify an at 
sign (@) in place of the object filename when you type the ASM 
command. For example 


ASM TESTPROGRAM, @ 


This command assembles the TESTPROGRAM file found in the 
current disk slot and drive, and generates assembly and symbol 
table listings, but does not produce an object file on the disk. 


You can have the Assembler store your object code directly into 
memory by using at in the ASM command in conjunction with an 
OBJ directive in your source program. This little-used feature of 
the Assembler is discussed in the description of the OBJ directive 
later in this chapter. 
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Coresident assembly: both your 
source text and the Assembler reside in 
memory at the same time. 





Coresident Assembly With a 64K Apple Il 


lf you are using an Apple Il system with at least 64K of memory, you 
can speed up the assembly of your programs by having the 
Assembler take your source text directly from the Editor's text 
buffer. Since the Assembler does not have to read your source 
program from a disk, this type of assembly is very quick. 


This option is called coresident assembly, because both the 
Assembler and your source text reside in memory at the same 
time. You cannot use any CHN (chaining), INCLUDE, or MACLIB 
directives in your source text if you wish to use coresident 
assembly. Neither can you use coresident assembly with a 48K 
Apple |i system, since there is not enough memory to store both 
the Assembler program and a full Editor text buffer. 


Warning 


You should be very careful to save your source program text to a disk 
before using the Assembler, because the Assembler overwrites the text 
buffer after it has assembled your program. 


To specify coresident assembly when you type the ASM command, 
type an asterisk (*) in place of the assembly-language source 
filename. The Assembler then takes the current contents of the 
Editor's text buffer as the source file for this assembly. You must 
specify the name of the object file that is to be generated, or you 
can suppress the generation of an object file as described above. 


For example, to initiate a coresident assembly, type 
ASM t. TEST OBJ, ,O2 


This command assembles the contents of the text buffer and 
stores the resulting object file on the disk in drive 2 of the current 
disk slot. If you do not specify a filename for the object file when 
using coresident assembly, the Assembler stores the object file on 
the current drive using the name OBJO. 





Recovering From Errors 


lf you make any syntax errors when you type the ASM command, 
the Editor/Assembler shows you an error message and places you 
at the Editor command level. 
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Appendix D contains an explanation of 
the DOS errors that may occur during 
operation of the Assembler. 


If the Assembler cannot locate a source file you specify, or some 
DOS error occurs, the Assembler aborts its assembly and returns 
you to the Editor command level. Before returning, the Assembler 
displays the message 


ASSEMBLY ABORTED. PRESS RETURN 


and waits for you to respond by pressing any key. To make sure 
that the Assembler has not aborted without closing all the open 
files, it is a good idea to use the .CLOSE command to make sure 
that any open files are closed. 


During assembly of your program source file, the Assembler 
displays individual messages for any errors it finds. These error 
messages appear on your screen or on your printer, depending on 
where you directed your assembly listings. 





Stopping Your Assembly 


You can stop the Assembler at any time during an assembly by 
pressing (CONTROL)-(C). When you press (CONTS0L)-(C), the 
Assembler closes all open files and frees any DOS buffers that are 
in use before returning you to the Editor command level. The 
Assembler does not remove any of the output files that it may have 
generated on your disk. To remove these files, use the direct 
.OELETE command from the Editor command level. 


There may be occasions where the Assembler will “hang up” after 
you type (CONTROL)-(C) to stop an assembly. For example, this can 
occur if the Assembler is directing output to a printer that is not 
on-line. To recover press and release twice, pausing 
between keystrokes. The Assembler terminates everything and 
returns you to the Editor command level. 





Warning 

Pressing during an assembly while the object file is being stored 
on a disk can be very, very dangerous for your disks. If the Assembler is in 
the middle of allocating output file space in the Disk Vtoc at the time you 
press (RESET), you can destroy access to your entire disk. Do not press 
during an assembly while the light on any disk drive is on; that is, 


while data is being written to a disk. 
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See the DOS User's Manual for a 
description of how to copy a file. 





The ASMIDSTAMP File 


You may recall from Chapter 2 that the Editor/Assembler 
maintains an ASMIDSTAMP file to keep track of your source disks. 


If an ASMIDSTAMP file doesn’t exist on this disk, the Assembler 
displays a warning FILE HOT F UAC message, although the 
Assembler continues assembling your source file. 


If there is an ASMIDSTAMP file on the disk, the Assembler 
increments the last six digits of this file and then saves the 
ASMIDSTAMP file back onto your source disk. If this disk is write- 
Protected, the Assembler displays a HR ITE FR NTECTED 
message and continues assembling your Program. 


The Assembler uses the data from the ASMIDSTAMP file when you 
use the DATE and IDNUM directives in your Program source file. 
These directives are described in the section “Controlling Your 
Assembly Listings.” They allow you to mark your Object files and 


programming session. 


You can copy the ASMIDSTAMP file from the DOS Programer’s 
Tool Kit Volume II disk onto your own Program source disks using 
the FID Program on your DOS System Master disk. 


Generating Assembly Listings 


Selecting a Printer to Receive Your Assembly Listings 


Before you call the Assembler from the Editor command level, you 
can select where the Assembler is to direct your assembly listings; 
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The PR# command lets you select a 
printer to be used later for your 
assembly listings. Note that the Editor's 
PRs command is different from that of 
Applesoft/DOS. Do not type a period 
before this PR= command. 


To select a printer or other device to receive your assembly 
listings, you must type the PR# command from the Editor 
command level. This command has the following syntax: 


PR#Heslot#Cl, CL#I CFP#I Cdevice-control-etringd J 


After you type this command, any assembly listings generated 
during the current Editor/Assembler session are directed to the 
specified device. Normally, you send your listings to a printer 
connected to a printer interface card, but you can also direct them 
to an 80-column terminal or some other output device. 


The slot number (slot#) you type specifies the interface card slot 
controlling the output device that will receive your listings. If you 
specify a slot number of zero, the Assembler directs your listings 
to the Apple II video screen. 


Warning 

If you specify F'F'# © (when your disk controller card is in slot 6) and later 
attempt to call the Assembler, the Editor/Assembler will stop and you will 
have to reboot. Always be careful to select the appropriate device when 
specifying an Apple II slot number. 


The Assembler can direct your assembly listings to only one output 
device at a time. It is possible that the output device you select 
may echo what it is receiving back to the normal Apple |! 40- 
column video-output routine, but this is up to your device and how 
you use it. The Apple II printer interface cards cannot print a listing 
that is wider that 40 columns and simultaneously echo to a 40- 
column Apple II screen. 


There are three other optional parameters that you can specify 
with the PR# command: 


è The first optional parameter is a logical-page length that 
indicates the number of lines you want the Assembler to print 
on a page. Unless you specify differently, the Assembler prints 
60 lines. You can specify a different logical-page length by 
typing followed by a two-digit number. 
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è The second optional parameter is a physical-page length, that 
is, the number of lines from one top-of-form to the next. You can 
specify the physical-page length by typing (P) followed by a 
two-digit number. If you used a SBTL directive in your source 
file and you do not specify a physical-page length, the 
Assembler outputs a form-feed character after each page. 


e The third optional parameter is a device-control-string, which 
is any sequence of control characters that your printing device 
requires to initialize it before printing the Assembier’s output 
listing. This device-control-string may not exceed 32 characters 
in length. For some Apple II printer interface cards, this typically 
consists of the normal (CONTROL)-(1_), (N) Sequence that turns 
off the Apple II screen and initializes the printer. You can type 
this sequence by holding down while you type (1), 
then releasing both keys and typing (N). 


When you type the PR# command, the Editor/Assembler 
preserves this information in memory and uses it for the remainder 
of your current session. When vou begin a new session with the 
Editor/Assembler, you must again specify where to direct your 
listings. A most convenient way to call the Assembler is to include 
this command with the Editor ASM command in a DOS EXEC file. 
You can then call the Assembler by executing the DOS EXEC 
command from the Editor command level. 


An example of the PR# command, as you would type it at the 
keyboard, is 


PR#H1, LS4 Pee £H 
where * represents (CONTROL)-(/ ). This command tells the 
Assembler to direct any assembly listings generated during this 
session to the printer with an interface card in slot 1. Listings will 


be printed with 54 lines on a page on paper that is 66 lines in 
length. 


Interpreting Your Assembly Listing 


You can direct the Assembler’s output listing to either the Apple || 
video screen or to an output device having an interface card in an 
Apple II slot. When you direct the listing to a device other than the 
video screen, the Assembler assumes that at least 80 columns of 
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Figure 3-1. A Typical Assembly Listing 


62 


print line-width are available for the listing. If your source lines and 
tabs are set so as to print beyond column 80, your printer must 
either wrap the lines itself or be able to receive more than 

80 columns of output from the Assembler. If you use at least one 
SBTL directive, headers are printed at the top of each listing page. 
The header consists of a title line followed by a blank line, as 
shown in Figure 3-1. 


81 CMOINTRP COMMAND INTERPRETER LS-JUN-31 #800018 PAGE 20 
---- NENT OBJECT FILE NAME IS OBJ 

BIA : BLOG 73 IRG s8C88 

AC Aa : Caen 34 EQITOP EO #0088 

Alaa: DAAR 31 ADSM EQU $0008 Bank 2 

ane ME SSSSSSSSCCSSS SSS SS SS SSeS SSS SS SSS: 
ACHA: 15 Br 34 COLO JMP TEXT Hard star tue 
ALAZ: AL 73 AL 35 IMF ETT NFT STAPT 
UCIS AS FF 34 TEXT LOM #$FF 

BCLS: 3A 35 TRS Force zt ach 
BC13;20 53 FC 36 JSP HOME 

ALIE: Re AÑ 37 LOY #8 

ACIO:63 BB 12 33 SENDBRNF LOR EANNEF, Y 

ac: FA jE BC28 33 BE EBANREND 

ACz: 20 ED FO 1AA JEP COUT 

ares: 181 IN‘ 


ACEDA FS ACIO 102 


BNE ZENDEAN 


L208:20 24 36 371 MINTRBS OFB 32.36.43 minimam tabs 


1208 WOES SSESSSSSSSSOSSCS SSS SSS SSeS eee sees ses 
L2HE : 313 LT ON 
1206:50 30 30 30 374 BANNEP OFE §Sd, 3d, 83d, $d. Sq, Fd 


EDITOR ASSEMBLEF II 


l2lisne CS C4 C9 i) al 
sse 


1225:81 BS AD CA 276 CATE 


The example in Figure 3-1 illustrates many of the features of the 
Assembler’s listing file format. The listing header contains the file 
number at the left, followed by the first eight characters of the file 
name, and the optional title. On the right are the date, ID number, 
and page number. Below the header is a blank line. 


The Assembler prints each source statement beginning with a 
four-digit hexadecimal number followed by a colon. This number is 
the value of the Assembler’s program counter (PC) when that line 
was assembled. Line 80 shows the expression-result field to the 
right of the PC field, typical of a control directive. 
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Press (SPACE } to interrupt your 


assembly listing. 





The Assembler shows the HET OBJECT ... message when it 
encounters an absolute ORG directive in your source program 
while the Assembler is directing its object output to disk storage. 
Lines 84 thru 102 show how normal 6502 code is printed, with the 
branch target address off to the right of the branch object code. 


Lines 871 thru 876 show how data directives are printed, with the 
NOGEN option in effect. The NOGEN option suppresses printing 
more than one listing line for data directives that generate more 
that four bytes of object output. Also note that lowercase is legal 
input for the Assembler; it is shifted to uppercase for internal use, 
but is printed as given in the source. 


Listing Tab Control 


The Assembler listing is tabulated in the same way the lines in the 
Editor are displayed. If the Editor tab settings are reasonable 
values when the ASM command is executed, the Assembler uses 
them to format the output listing. The Assembler uses these 
settings if the first tab setting is 12 or more, and uses its minimum 
tab settings otherwise. The minimum settings are equivalent to 
Editor tabs of 15, 19, and 31. The Assembler uses only the first 
three Editor tabs. Large Editor tab settings may cause listings to 
be shifted off the printed page. 


Interrupting the Listing 


You can make the Assembler pause when it is displaying or 
printing an assembly listing by pressing (SPACE). This interrupts 
the Assembler output, allowing you to view portions of the listing. 
To restart the listing, type any character that is not a mode 


character, (CONTROL)-(0), or (K), to the Assembler. 


You can single step through the listing a line at a time by pressing 
once for each line. If you are viewing the assembly listing on 
a 40-column video screen, you can view the second half of the 80- 
column listing (columns 41-80) by pressing (ESCAPE). Pressing 

a second time allows you to single step through the 
comment portions of your listing. To continue the assembly at 
normal speed, type any key other than or (SPACE). 


Turning Off the Assembly Listing 


To control the portions of your source program printed in the 
assembly listing, you typically use the Assembler’s LST ON/OFF 
directive in your program source file. You can also control the 
listings from your Apple Il keyboard during assembly. Your 
keyboard commands override the current state of the LST option 
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until the next LST directive in your source program or your next 
command from the keyboard. Using these keyboard commands, 
you can examine sections of the listing you turned off from within 
your source program, or you can turn off the listing of sections that 
your source program directed be listed: 


è To turn the listing off, type (CONTROL)-(N), where N means ‘not 
listed.” 


@ To turn the listing on, type (CONTROL)-(0). 


Remember that the Assembler can encounter a LST directive 
within the source program that counteracts your most recent 
(CONTROL)-(N) Or (CONTROL)-(0) command. To correct this, just 
retype your command from the keyboard. Normally, you use these 
commands only when you are working on large programs; 
however, when you change a small portion of your program, for 
example, you may not want to list the entire program. 


The Symbol Table Listing 


After generating your assembly listing, the Assembler normally 
Produces an optional symbol table listing, which can be sorted in 
either alphabetical or symbol-value order. You can suppress the 
Printing of this listing if you abort the assembly by pressing 


(CONTROL )-(N ) 


or if you use the LST NOASYM,NOVSYM directive in your source 
program. To produce only the symbol table listings, use the LST 
OFF directive at the beginning of your source file and a LST 
ASYM,VSYM at the end of your source program. 


When the Assembler prints the symbol table, it automatically 
adjusts the width of the symbol table output for the Apple || 40- 
column screen or for a printer, which is assumed to be 80 columns. 
The Assembler displays the table in two columns on the screen 
and prints it in either four or six columns on the printer, depending 
on the option you select with the LST directive. 


The Assembler prints each entry in the symbol table using the 
following format: 


èe The first character in each entry indicates special information 
about that particular symbol: 


X indicates an external symbol (see EXTRN directive) 

N indicates an entry point symbol (see ENTRY directive) 
? indicates a symbol defined but never referenced 

* indicates an undefined symbol 
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Figure 3-2. A Sample Symbol Table 
Listing 


Any text file that you create using the 
Editor is accepted by the Assembler as 
a valid input file. 





If an undefined symbol appears in the symbol table, your assembly 
must have generated one or more Hi SLICH LABEL errors. 


è The next four characters contain the two- or four-digit 
hexadecimal value defined for the symbol. A zero-page or 
single-byte address is identified by two spaces before the two- 
digit address; a two-byte address is displayed using all four 
digits (even if the two leading digits are zero). 


è The remaining 14 characters are the first 14 characters of the 
symbol’s name. All unique symbols appear in the symbol table, 
but only the first 14 characters of any symbol name are ever 
printed. 


Figure 3-2 shows an example of a symbol table listing sorted 
alphabetically by symbol name. 


WS S/MBOL TABLE 2OFTED BY SYMBOL 27-JUN-31 #00098 PE 22 
0 ADPTR SF AOTBLNO 203E ALPHAS 24 CH 
NECEG 2 MOUMP Ware SYTYPE 206E SWAP = -°20F4 SWIPEIT 
ESF TABLENO *2E84 TESTLEL ° ØA TXTBEG 77 VAL 
K2ES9 KANSKA TE ‘VV RM ‘eCan 


Assembly-Language Source Files 


The Assembler accepts normal DOS text files as its assembly- 
language source input. A normal DOS text file is a file of logical 
records, where each logical record is a sequence of ASCII 
characters terminated by an ASCII carriage return ($8D). Each 
ASCII character must have its most significant bit (msb) set to a 
one. 


There is a great deal of additional structure that your source files 
must contain before the Assembler is able to assemble your 
source file into an executable 6502 object program. Each line or 
logical record of your assembly-language source file must be 
recognized by the Assembler as a valid assembly statement. The 
sections that follow discuss the syntax of these assembly 
statements. 


CC 
The Syntax of Assembly Statements 


Each line of an assembly language source file is called an 
assembly statement. Assembly statements consist of either an 
instruction statement or an Assembler directive. The Assembler 
allows only one assembly statement per source line. Assembler 
directives and instruction statements follow the same general 
syntax. 
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Although the Editor allows you to use 
any character as an Editor tab 
character, the Assembler recognizes 
only the space or tab (CONTROL)-(T) 


character to separate fields. 


An identifier is a symbolic name or 
character string that represents a 16-bit 
numeric value. 


An assembly statement is divided into four fields: 
è the label field 


è the mnemonic or operation field 
è the operand field 


@ the comment field. 


These fields are arranged in the following order 


[label] mnemonic [operand] [comment] 


An example of an assembly statement is 


BEGIH LOX #64 : liad zize of buffer tabe clesgrec 


Notice that all the fields are optional except the mnemonic or 
operation field. The only assembly statement that cannot contain 
anything in the mnemonic field is a pure comment line. This special 
assembly statement is a line where the first character is an asterisk 
or a semicolon. 


These fields must be separated by a space or tab ((CONTROL)-(1 }) 
character. To skip over a field, use two spaces or tab characters in 
the assembly statement. When you use the Editor to create your 
program source file, the Editor uses these tab indicators to format 
the display of your program. 


The Label Field 


The label field is optional in an assembly statement. Any assembly 
statement except a pure comment can have a label. To label an 
assembly statement, you must place an identifier starting in the 
first character position of the line. 


An identifier is a symbolic name that represents a 16-bit numeric 
value. Whenever you place an identifier in the label field of an 
assembly statement, you are defining a numeric value to be 
associated with that identifier. This numeric value is either the 
memory address that is the current value of the Assembler’s 
program counter, or the value of the operand expression if the 
identifier precedes an EQU directive. The Assembler issues a 
OURPLICATE SYMEOL error if you attempt to define the same 
identifier more than once in a program. 


An identifier is a character string starting with a letter and 
containing only letters, digits, and periods. All the characters in an 
identifier are meaningful, except that lowercase and uppercase 
letters are treated the same for all purposes except printing. 
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A mnemonic is a character String that 
represents an instruction, an assembier 
directive, or an assembly macro. 


There is no arbitrary limit to the length of an identifier you can use 
with the Assembler. Longer identifiers tend to slow down the 
assembly of your programs, since it takes time to compare all the 
characters. They also require more space in the symbol table. As a 
practical matter, you should limit identifiers to eight or ten 
characters. 


The one-character identifiers A, X, and Y represent registers in the 
6502 microprocessor. You cannot use these identifiers to refer to 
any other register, address, or data in your source programs. Since 
some 6502 assemblers also reserve the use of the S and P 
identifiers, you should not use them if you want to keep your 
source programs compatible with other 6502 Assemblers. 


You can define any absolute identifiers, or 16-bit identifiers, 
anywhere in your Program. If you want to use a zero page 
identifier, one that refers to an address less than 256 decimal, you 
must define this identifier by using either a DSECT or EQU 
directive before you use it in an operand expression. If you use an 
identifier before you define it, the Assembler is forced to assume 
that the identifier refers to an absolute (two-byte) memory 
address, even if you later define the identifier to represent a zero- 
Page or one-byte address. 


It is a good practice to define all your data identifiers at the 
beginning of your Programs. You can do this by using the 
Assembler’s EQU, DSECT. and DEND directives. 


The Mnemonic Field 


The second field of an assembly source statement is the 
mnemonic or operation field, and must always contain a valid 
mnemonic. This mnemonic must always be separated from the 
identifier in the label fieid by at least one space. If you do not 
include a label in an assembly statement, you must include at least 
one space before the mnemonic. 


A mnemonic consists of two or more letters terminated by a space. 
A mnemonic can represent one of the following: 

e a6502 assembly-language instruction 

® an Assembler directive 


e an assembly macro that you have defined. 
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A complete list of the assembly- 
language instructions and assembler 
directives recognized by the 
Assembler: see Appendix B. 


Assembly directives: see the section 
“Giving Directions to the Assembler.” 


Macros: see the section “Using Macros 
in Your Programs." 


The mnemonics representing 6502 assembly-language 
instructions are the standard MOS Technology mnemonics. The 
Assembler also recognizes several additional synonyms for 
branching instructions. 


Assembler directives, or pseudo-operations (pseudo-ops), are 
instructions to the Assembler that direct the course of the 
assembly, define program data, reserve space, or perform other 
assembly chores. 


An assembly macro is a set of assembly-language instructions 
that are inserted into your assembly program by the Assembler. 
You call a particular macro by using the name of that assembly 
macro in the mnemonic field of an assembly statement. 


The Operand Field 


The operand field of the assembly statement is required only for 
some assembly instructions, Assembler directives, and macros. 
When you use a mnemonic for an instruction, directive, or macro 
that requires one or more operands, you must include these 
operands in the operand field, separating each operand by a 
comma. There must be no spaces within or between operands. 


Each operand in the operand field must be one of the following: 

e aregister 

e an identifier 

è aconstant 

èe an expression composed of constants, identifiers, and one or 
more operators. 


Registers 


Registers in an operand field refer to the 6502 microprocessor 
registers. You can reference these registers using the reserved 
identifiers A, X, and Y. 


identifiers 
Identifiers are described in the section “The Label Field.” When 
you use an identifier in the operand field, the Assembler evaluates 


the operand by replacing your identifier with the 8- or 16-bit value 
that the identifier represents. Somewhere in your program, either 
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before or after you use the identifier in an operand field, you must 
define a value for each identifier that you use. If you do not define a 
value for an identifier, the Assembler displays an appropriate error 
message. 


Constants 


A constant in an assembly language program defines an explicit 
value. You can define two different types of constants in your 
programs: numeric constants or string constants. 


A numeric constant represents a one- or two-byte numeric value. 
You can represent a numeric constant in any of four notations: 
decimal, hexadecimal, binary, or octal. 


@ in decimal notation, a numeric constant is represented in base 
ten by a positive integer between 0 and 65535, composed of 
digits from 0 through 9. If you use a value greater than 65535 as 
a numeric constant, the Assembler gives you a numeric 
overflow message. 


è in hexadecimal notation, a numeric constant is represented in 
base sixteen by a dollar sign ($) character followed by up to four 
hexadecimal digits. The hexadecimal digits are 0 through 9 
and A through F. 


è in binary notation, a numeric constant is represented in base 
two by a percent (%) character followed by any 16-bit binary 
number. This binary number is composed of the digits 0 and 1. 
If you use more than sixteen digits in this binary number, the 
Assembler gives a numeric overflow message. 


è In octal notation, a numeric constant is represented in base 
eight by an at (@) character, followed by up to six octal digits. 
The octal digits are 0 through 7. 


String constants represent sequences of ASCII characters. You 
can represent a string constant in your source program by 
enclosing the characters between single quotes: 'A’ and ‘AE’ are 
valid string constants, for example. A string can be up to 

240 characters in length, but all the string must be defined on a 
single line. When you use a string constant as the operand of an 
immediate-mode instruction, you need not use a trailing quote, 
since such an operand can be only one character. 
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MBS, DCI, ASC directives: see the 
section '‘Generating Data in Your 
Object Code” in this chapter. 


= high-byte operator 
= low-byte operator 
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When a string constant is assembled, the Assembler allocates one 
byte for each character. The lower seven bits of each byte 
correspond to the ASCII code for that character, and the most 
significant bit (msb) is either set or not set. You can use the MSB, 
DCI, and ASC directives to control the state of the most significant 
bit. 


Expressions 


The Assembler recognizes and evaluates simple numeric 
expressions that you can use in place of a numeric constant or 
identifier. A numeric expression consists of constants, identifiers, 
and one or more operators. 


The Assembler recognizes the four arithmetic operators +, -, *, 
and / (addition, subtraction, multiplication and division) for use in 
expressions. When performing these arithmetic operations, the 
Assembler does not check for numeric overflow of the results; it 
just retains the 16-bit results. This lets you perform wraparound 
memory-address calculations using these operators. 


The Assembler also recognizes three binary-logic operators that 
perform logical AND, OR, and exclusive-OR operations on two 16- 
bit values. The characters used to represent these operators are 
the caret (-), the vertical bar (|), and the exclamation point (!), 
respectively. Note that these are full 16-bit operators and can 
produce unexpected results if applied to eight-bit constants or 
expressions; this is especially true of the exclusive-OR operator. 


High-Byte and Low-Byte Operators 


The Assembler always maintains a 16-bit value when it evaluates a 
numeric expression. To extract an eight-bit result from this 16-bit 
value, you can use the high-byte (<) and low-byte (>) operators to 
extract the high-order or low-order byte from a 16-bit value. To 
help remember the meanings of the characters that represent 
these operators, think of them as arrowheads pointing either to 
the left or the right half of a hexadecimal constant. For example, 


<($FF11) is equivalent to $FF, and 
>($FF11) is equivalent to $11. 
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The syntax of a valid Assembler expression, in Backus-Naur Form 
(BNF), is 


Term := Constant , Identifier 
rs te ER! 
Byteopr:= >, < 


Expression := [Byteopr] Term [Opr Term]...] 


This syntax definition says An expression is a term preceded by an 
optional byte-operator and followed by one or more optional 
[operator term] sequences. The Assembler evaluates each 
operator from left to right. If you do not follow this syntax when 
forming an expression, the Assembler signals an assembly error. 


You cannot use an arithmetic or logical operator as the first 
element of an expression, nor can an operator be the last element. 
The only exceptions are the plus and minus operators (+ and -), 
which can be used to indicate a positive or negative expression. 


Your expressions cannot contain blanks: if an expression contains 
a blank, the part after the blank is treated as a comment and 
ignored by the Assembler. 


If you direct the Assembler to generate relocatable object code 
(using the REL directive), the Assembler will not allow 
multiplication, division, or the binary-logic operators to be applied 
to a relative identifier or subexpression. These expressions will 
generate a nonrelocatable result. Also, the high- and low-byte 
operators generally will not produce a correct relocatable result. 
This restriction applies only if you use the REL directive to 
generate relocatable output from the Assembler. 


The Location Counter 


You can use the asterisk (*) in an operand expression to represent 
the current value of the Assembler location counter. The asterisk 
always represents this value at the beginning of the line or 
statement containing the asterisk. If the asterisk follows an 
instruction mnemonic, the location counter points to the address 
of the first byte of that instruction code. 
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You can perform addition or subtraction operations on the value of 
the location counter. You can also use the high-byte and low-byte 
operators on this value. These operators let you align code or data 
Structures at specific positions relative to a memory page. For 
example, the statements 


HEFEL Em t defines HEFEL az the low- 
bute of Current PE 
os F$1QH—-HERPEL ; fill to mext page boundary 
HEWFACGE EGU ¢ [start of next memory page 


create an unused data area up to the next page boundary. The 
code or data that follows is aligned from byte zero of the next 


page. 


The advantage of using this method is that it always produces 
page-aligned code even when the size of the program preceding 
this code changes as revisions are made. This method can also be 
used to align code to other specific positions in a page and it can 
be used with the ORG directive to make relative ORG adjustment 
to the location counter. 


Zero-Page Addressing : 


The Assembler normally generates a two-byte or zero-page 
instruction whenever the operand is a properly defined zero-page 
identifier or expression. Sometimes, however, you may want to 
generate an absolute or three-byte instruction that refers to a 
zero-page address. To bypass this Assembler rule, you must 
equate the identifier to the desired zero-page value only after you 
have referenced the identifier at least once in an operand 
expression. The Assembler will then treat the identifier as an 
absolute identifier for the remainder of the assembly, generating 
absolute-audressing opcodes for all instructions that use this 
identifier. 


The Comment Field 


The comment field is an optional field that you can use to 
document what your program is doing. The Assembler prints the 
comment field in its program listing, but for all other purposes the 
comment field is ignored. 
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Assembly directives direct the 
Assembler to perform certain 
operations during assembly of your 
program. 


A comment can contain any arbitrary set of ASCII characters and 
must be separated from the operand field by a space. In addition, 
the comment must begin with a semicolon if you want the Editor 
truncation facility to operate. The Assembler also recognizes 
statements that begin with an asterisk or a semicolon as the first 
character on the line. These statements are treated entirely as 
comments, and, although they appear in listings, they are 
otherwise ignored by the Assembler. 


Giving Directions to the Assembler 


Assembly directives are instructions that you put into your 
program source file to direct the Assembler to perform certain 
operations during the assembly of your program. Statements 
containing assembly directives resemble those containing 
machine instructions in that both statements can contain label, 
mnemonic, operand, and comment fields. Unlike machine 
instructions, however, assembly directives are not assembled into 
executable 6502 machine opcodes. Only the data-definition 
Assembly directives generate actual data that is included in the 
resulting object program. 


The directives that are recognized by the Assembler perform a 
variety of functions, including 

èe controlling the overall assembly of a program 

èe assigning information 

è generating data to be included in the object file 

è controlling the conditional assembly of portions of a program 


è controlling any additional source files and macros that are used 
in an assembly 


è controlling what type of object code is generated during 
assembly 


è controlling the way assembly listings are printed. 


The following sections describe each assembly directive that is 
recognized by the EDASM Assembler. Many of these directives are 
specific to the EDASM Assembler, although you will probably 
recognize similarities to other assemblers. The required syntax of 
the statement containing the directive begins each section. Where 
labels are not shown, you can include an optional label; any 
statement can also include a comment. 
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C 
Controlling the Overall Assembly 


You use the directives described in this section to direct the 
overall assembly of your source program. These directives 


® control the addresses at which your program is assembled; 


e let you generate dummy code sections to define memory 
locations your program can access or constants that it can use; 


e control the type of object code (load-image binary object or 
relocatable object code) that the Assembler generates; 


è let you use and generate the Apple II SWEET 16 opcode 
mnemonics that access the ROM-coded 16-bit pseudomachine 
in your Apple II system (only if you have an Apple II with an 
Integer BASIC ROM). 


To use these directives, include the directive mnemonic like any 

other mnemonic in an assembly statement; some of the directives 

also require an operand in the statement. You can precede any i=. 
directive with a label and follow any directive with a comment. 


ORG 


Form: ORG expression 


The ORG directive establishes the origin address of your object 
code. You must use at least one ORG directive in your source file 
before the Assembler can begin generating object code output to 
a disk. 


The Assembler recognizes two kinds of ORG directives: absolute 
and relative. A relative ORG is one whose operand expression 
contains relocatable identifiers. You must have previously defined 
all the identifiers that you use in the operand expression. Some 
examples of relative ORG directives are: 


GEG {+5 
MRIS STM +18 
ORG #$-208 


These relative ORG directives update the Assembler’s internal 
location counter for the current object file. The Assembler updates 
this counter both forward and backward in relation to your object 
file. If you increase the value of the counter, the Assembler fills your 
object file forward to the new position with random data; if you 
decrease the value, the Assembler deletes any object code that it 
previously generated for addresses above the new value of the 
counter. 
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An absolute ORG directive is one whose operand contains an 
absolute expression, typically a constant. You use an absolute 
ORG directive to define the starting address the Assembler uses 
to generate object code. The Assembler also places this starting 
address in the output object file so this address can be used by 
DOS when you later load the object file using the DOS BLOAD or 
BRUN commands. 


You normally use only one absolute ORG directive in your program 
source file. The Assembler generates a new output object file for 
each absolute ORG it encounters in your source file, closes the 
current object file, if any, and starts a new file. The filename that 
the Assembler uses for each new object file is generated by 
incrementing the last character of the previous object filename. If 
you want to generate multiple object files by using more than one 
absolute ORG in your source program, you must use these 
multiple object files properly, or combine them if required for later 
execution. 


DSECT 
Form: DSECT 


You can use the DSECT directive to define an area of memory, 
such as a data table or the 6502 zero page, without actually 
generating any object code to reside in this memory area. The 
DSECT directive marks the beginning of a block or group of 
statements in which you define the values of identifiers that you 
use elsewhere in your program. You use these identifiers to 
reference locations within the DSECT memory area. You 
commonly use the DSECT directive to define the labels of data 
items and pointers in the 6502 zero page. 


The name DSECT comes from Dummy SECTion, so called 
because the Assembler generates no object code for this section. 
You can use the DSECT directive to suspend object code output 
temporarily and set the Assembler’s location counter to address 
zero. Once you start a DSECT memory area, it remains in force 
until the Assembler encounters a DEND directive. You can include 
any assembly statements, including the ORG directive, within this 
DSECT area. 


If you include an ORG directive within a DSECT, the ORG only 
controls the addresses that the Assembler assigns to identifiers 
within the DSECT. The Assembler does not treat these ORG 
directives as absolute ORGs, nor do they alter the Assembler’s 
normal location counter that is saved for the duration of the 
DSECT area. 
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You cannot nest DSECT areas, that is, you cannot use a DSECT 
directive between the occurrences of a DSECT/DEND pair of 
directives. If you do, the Assembler signals a (SECT. CEHO error. 


DEND 

Form: DEND 

The DEND directive marks the end of tt urrent DSECT area. 
When the Assembler encounters a DEND directive, it resumes 
generating object code where it stopped after encountering the 


DSECT directive. The Assembler restores its normal location 
counter address that it saved during the DSECT area. 


This example shows how you can use the DSECT and DEND 
directives: 


OSECT 


ORIG Fan 
CEFIHE ZERO-PAGE STORAGE 

ARE Cis: 2 
EREIS C's 2 
DREG Cis, 2 
H Li's, 1 
È O's 1 

GREG Faun 
TENTFG 1 os $400 

CIE HCI 





Warning 

If you start a DSECT area with the DSECT directive and never end this 
area with a DEND directive, none of the assembly statements following 
the DSECT directive appears in your object file output. These statements 
appear in listings just as in a normal assembly, but no object code is 
generated. This ‘missing DEND" problem can cause mysterious loss of 
object code in your output files. 
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Relocating Loader routines: see 
Chapter 5. 


RLOAD program: see Chapter 5. 





OBJ 


Form: OBJ expression 


The OBJ directive is useful only if you want to assemble your 
program and place the object code directly into memory rather 
than store it on a disk. When you suppress the generation of an 
object file by typing the ASM command with the @ option for the 
object filename, the Assembler generates no object output unless 
you use this directive to specify where in memory to put the object 
code. 


The Assembler performs very specific checks on the expression 
given in the OBJ directive. The Assembler does not allow a value 
less than the current end of the Assembler’s symbol table; you see 
the error message WIE. MEMORY COHFLICT if you attempt to use 
such a value. In addition, the Assembler does not allow a value 
greater than the HIMEM value passed to it by the Editor; in this 
case, or if the object code output exceeds this limit during an 
assembly, you see DEJ MEMORY OVERFLOW. 


You cannot use the OBJ directive if you use the REL directive to 
generate relocatable object code output. 


REL 
Form: REL 


When you use the Relocatable (REL) directive, the Assembler 
generates relocatable object code. The Assembler does this by 
creating a relocation dictionary that is appended to the end of 
your object code. This relocation dictionary is used by the 
Relocating Loader program to load your object program and 
prepare it for execution at any starting address. 


The Assembler produces a relocation dictionary only if you include 
the REL directive at the beginning of your source program before 
you use or define any identifiers. 


When you use the REL directive, your object file is given a file type 
character of A, for relocatable, in the DOS disk catalog. The 
format of this type file is described in the Appendixes. A 
relocatable object file cannot be loaded by using the DOS BLOAD 
or BRUN commands. It can only be loaded by the RLOAD 
program. 
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Apple II SWEET 16: see Appendix G. 


SWEET 16 instruction summary: see 
Appendix G. 
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The REL directive requires no operand. You cannot use this 
directive in a source program containing an OBJ directive to 
produce coresident object code output. 


When the Assembler generates relocatable object files, it clears 
the relocation dictionary each time it encounters an absolute ORG 
directive. Each segment of your assembled object code has a 
separate relocation dictionary. 


SW16 


Form: SW 16 [expression] 


If you have an Apple ll, this directive lets you use the SWEET 16 
routines that are coded in the Integer BASIC ROM. Appendix G 
explains how to include these routines in your own program; this 
allows you to use them on any type of Apple II. 


When the Assembler encounters the SW 16 directive in your 

program source file, it turns off its generation of SIIEET16 ~ 
LIF ICE warnings and inserts a JSR instruction in your object file 

output. This subroutine jump is normally to the Integer Basic ROM 
SWEET 16 entry point, $F689. If you include the optional address 
expression in the operand field, the Assembler generates the JSR 

to that address instead. 


You normally follow this directive with Apple II SWEET 16 
mnemonic instructions, ending with a SWEET 16 RTN instruction. 
If you use these mnemonics in your source file without including 
the SW 16 directive, the Assembler does not assemble them, but 
instead signals a 2WEET1c OFCOCTE warning. This warning 
prevents your accidental use of the Sweet16 mnemonics, many of 
which are very similar to standard 6502 mnemonics. 


De eee 
Assigning Information 


You use the directives described in this section 

è to assign numeric values to identifiers: 

è to define the characteristics of an identifier that references or is 
referenced by another assembly-language program. 


You include these directives—some require an operand—like any 
other mnemonic in an assembly statement. You can precede any 
directive with a label, and you can follow any with a comment. 
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EQU 


Form: identifier EQU expression 


You use the Equate (EQU) directive to define the value of a 
symbolic identifier. The identifier that you place in the label field 
cannot be defined elsewhere in your program. The Assembler 
evaluates the expression in the operand field and defines the 
identifier to have this numeric value. You cannot use any external 
identifiers in the operand expression. 


You can use symbolic identifiers 


e To represent frequently used or changeable program constants, 
allowing you to make simple changes without having to edit 
many lines of the program. 


e To name items of information that have special meanings. This 
makes your programs more readable and easier to understand 
and change long after they are written. 


DEF or ENTRY 
Form: DEF identifier or ENTRY identifier 


The DEF directive allows an identifier defined in a particular 
module of your program to be referenced as an external symbol by 
other modules. You can use this directive more than once in a 
module, either to define global identifiers or to define alternate 
entry points for your module. 


When you use the DEF directive in an assembly statement, the 
identifier in the operand field is marked as a global or entry point 
identifier. Normally, the value of this identifier will be defined 
elsewhere in your program. You can, however, define the current 
value of the Assembler’s location counter as a global entry point 
by including this same identifier in the optional label field of the 
statement containing the DEF directive. You must not use the DEF 
directive inside a DSECT. 


Whenever you assemble a module containing the DEF directive 
and select relocatable object code using the REL directive, the 
Assembler appends an External Symbol Directory (ESD) to the 
Relocation Directory (RLD) of your object code output. This 
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external symbol directory contains all the global identifiers and 
external symbols defined in your module. It also includes 
information necessary for a Linker or Linking Loader program to 
link this module to other modules that may reference these entry 
points or global identifiers. 


ZDEF 
Form: ZDEF identifier 


You can use the ZDEF directive to create a zero-page global 
identifier in the same way that you use a DEF or ENTRY directive to 
create an absolute identifier. All the rules that apply to 
DEF/ENTRY apply to ZDEF except that the identifier must be a 
zero-page identifier. Use the ZDEF directive only after the identifier 
is defined as a zero-page identifier, or the Assembler will signal an 
ILLEGAL LAEEL error. 


EXTRN or REF 
Form: EXTRN identifier or REF identifier 


Use the external (EXTRN) directive to indicate that an identifier is 
not defined in a particular module, but is instead defined 
externally. The Assembler always treats these identifiers, or 
external symbols, as two-byte identifiers, never as zero-page 
identifiers. If you use an external symbol as the operand of an 
instruction, the Assembler generates two empty bytes in the 
address portion of that instruction. 


lf you are generating relocatable object code using the REL 
directive and you use the EXTRN directive to define symbols as 
external, the Assembler adds an external symbol directory after 
the relocation directory in the relocatable object file. 


To execute your program module containing external symbols, you 
must first use a Linker or Linking Loader program to link this 
module with one or more additional program modules where these 
external symbols are defined. A Linker resolves all of these 
external references using data from the external symbol 
directories of each module, and links all the modules into a single 
executable object program. 


You can include a label identifier in the label field of the statement 
containing the EXTRN directive. This label is defined with the 
current value of the Assembler’'s location counter. The identifier 
that follows the EXTRN directive in the operand field is defined as 
the external symbol. 
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ZXTRN or ZREF 
Form: ZXTRN identifier or ZREF identifier 


This directive serves the same purpose for zero-page globals that 
EXTRN or REF does for absolute global identifiers. You must use 

this directive to define an identifier as a zero-page identifier before 
you reference it in the operand field of an assembly statement, or 
the Assembler will signal the error message ILLEGAL LHEEL. 


A Note on External Symbols 


You can use the DEF, ENTRY, ZDEF, EXTRN, REF, ZXTRN, and 
ZREF directives when you are producing a relocatable object file 
or a binary object file. To run correctly a program that contains 
references to external identifiers, you must first use a Linker or 
Linking Loader to link this module to other program modules in 
which all these external references are resolved. 


Notice: Although no such Linker or Linking Loader currently exists, 
these directives are provided here for completeness if you want to write 
your own Linker or if a Linker or Linking Loader program becomes 

e available. 


When you are creating self-modifying code, you can also make use 
of external symbols to define addresses that are filled in at 
execution time. The DEF and ZDEF directives do not cause 
anything to appear in the machine code portion of the object file; 
the EXTRN and ZXTRN directives allow undefined symbols to 
remain undefined without causing Assembler error messages. 





Generating Data in Your Object Code 


You use these Assembly directives to allocate or define data areas 
within your assembly-language program. These directives allow 
you to define 


è byte and word data 
è address tables 

èe data storage areas 

e ASCII character data 
è message strings. 


You can precede each directive with a label, and you can follow 
each with a comment. 


Giving Directions to the Assembler 





82 





DFB or DB 
Form: DFB expr[,expr...] or OB expr[,expr...] 


Use the Define Byte (DFB) directive to define one or more bytes of 
data to be placed in the object file. The Assembler evaluates each 
expression and uses the resulting value, modulo 256, as the value 
for each byte. If you use an identifier in the label field of the 
statement containing the DFB directive, this identifier represents 
the address of the first byte generated. If the bytes that are 
generated are calculated from a relocatable expression, an entry is 
made in the RLD for each such byte so that its value can be filled in 
during relocation. It is better to use multiple DFB directives— 
limiting each DFB directive to five to ten expressions —rather than 
use a large number of expressions in the operand of one DFB 
directive. 


The comma is the only valid delimiter between expressions. You 
cannot use blanks between the expressions in the operand. You 
can use any valid expression in the operand field. 


DW 
Form: DW expr[,expr...] 


Use the Define Word (DW) directive to define two-byte 6502 words. 
A 6502 word is special in that the lowest eight bits of the 16-bit 
expression are stored in the first of the two bytes, and the most 
significant, or high eight bits, are stored in the second byte. You 
must use this order of the bytes to be able to use the 16-bit 
address as an indirect-address pointer in the indirect-indexed and 
jump-indirect 6502 instructions. 


The label field identifier is given the value of the program counter, 
which is the address of the first, or low-order, byte of the first word. 
If you use more than two expressions, only the first two appear in 
program listings unless you turn on the LST GEN option. 


DDB 

Form: DDB expr{,expr...] 

The Define Double-Byte (DDB) directive is like the DW directive, 
except that the bytes are stored in reverse order, with the high- 
order byte first and the low-order byte second. The label-field 


identifier has the address of the first byte—the high-order byte— 
of the first double byte expression. 
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DS 
Form: DS expr[,expr] 


Use the Define Storage (DS) directive to reserve a group of bytes 
without defining any data to be stored in these bytes. The first 
expression of the DS directive can contain identifiers only if you 
defined them earlier in your program. This expression cannot have 
a value greater than 16384 decimal. 


If you include a second expression in the operand field, the 
reserved bytes are filled with the value of this expression. If you 
include only the first expression in the operand field, the reserved 
bytes contain random values. 


The size of your output object module includes the amount of 
space reserved by the DS directive—the file is filled with data. For 
example, if you accidentally enter a DS with an expression that 
results in a value of 12K bytes, you'll suddenly get a very large 
output file. Use this directive only for small data areas to avoid 
wasting storage space on your disk. Since you do not need to store 
large buffers and work areas with your executable object program, 
do not define them by using this directive. 


If you include an optional identifier in the label field of this 
statement, the identifier is assigned the address of the first byte of 
this allocated storage. 


When you use a DS directive inside a DSECT, the Assembler does 
not actually place any code in the object file. Using DS statements 
within a DSECT is an easy way to define a data structure that can 
later be modified and the program reassembled without affecting 
other assembly statements in the source program. 


MSB 
Form: MSB ON or MSB OFF 


The Most Significant Bit directive (MSB) provides a means of 
controlling the value of the most significant bit (msb) of the ASCII 
characters that are generated by the Assembler. You can use this 
directive as many times as necessary in your assembly program. 
The ASCII characters affected by MSB are those generated as 
immediate string constants and as the string operand of the ASC 
directive, but not of the DCI directive. 


The Assembler default is MSB ON because the APPLE II Monitor 
routine COUT expects ASCII characters in this form for normal 
display. 
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ASC 
Form: ASC .string. 


The ASCII (ASC) directive defines a string of 8-bit bytes in the 
output object file that are filled with the ASCII values of the 
characters in the operand string of the directive. Four or fewer 
bytes are printed on each source line—without a line number — if 
the LST Gen option is in effect for the directive. When the LST 
NOGen option, the default, is in effect, only one line and the first 
four bytes are printed. If a label is present on the ASC directive, it 
is assigned the current value of the program counter—the address 
in memory of the first character of the string constant. 


The operand string (shown above as .string.) is a delimited string 
that begins with any character that does not occur in the string 
and is optionally terminated with the same delimiter. You can omit 
the terminating delimiter if you also omit the comment field in the 
assembly statement. The MSB directive determines if the most 
significant bit of each character in the generated bytes is a one or 
a zero. 


STR 
Form: STR .string. 


The String (STR) directive provides a easy method of creating a 
string of ASCII characters preceded by a count byte. The count 
byte contains the number of characters in the string, not including 
the count byte itself. The MSB directive determines if the most 
significant bit of each character in the generated bytes is a one or 
a zero. 


DC! 
Form: DCI .string. 


The DCI directive functions just like the ASC directive, except that 
the MSB directive does not control the most significant bit of each 
byte. Instead, the Assembler generates all bytes of the DCI string 
with a most significant bit of zero, except for the last byte, which 
has a most significant bit of one. 
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Conditional assembly: a process that 
lets you assemble only selected 
Portions of your Program so the same 
source program can be used to 
generate several executable versions. 


A conditional assembly block is a 
group of source statements that are 
assembled only if certain conditions are 
met. 


DATE 
Form: DATE 


This directive generates nine bytes of ASCII data in the Output file. 
These bytes occupy locations $3B8 thru $3C0 that normally 


date is typically a sequence of ASCII characters in the DD-MMM- 
YY format. If the Editor did not find the ASMIDSTAMP file when 
you initially ran the Editor/Assembler Program, the Date directive 
generates nine ASCII nulls with the most significant bit on. 


IDNUM 

Form: IDNUM 

This directive generates six bytes of ASCII data, that occupy 
locations $3C3 through $3C8, in the output file. These locations 


normally contain the six-digit ASCII number portion, with the most 
significant bit on, of the ASMIDSTAMP file. Since the Editor 


Controlling Conditional Assembly 


The Assembler recognizes a number of Assembly directives that 
let you control the sections of a Program source file that you want 
to include in the assembled object file. This Process is known as 
conditional assembly. Conditional assembly is useful when you 


DO, IFXX, ELSE, and FIN 


All these conditional-assembly directives function together to 
mark the beginning and end of a section of conditional-assembly 
source statements called a conditional assembly block. 


© The DO directive marks the beginning of a conditional assembly 
block. 


è The FIN directive marks the end of a conditional assembly 
block. 
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Items within square brackets [ ] are 
optional. 


è The ELSE directive divides the statements between the DO and 
FIN directives into two conditional assembly blocks; the second 
conditional block is an alternate block that is assembled only if 
the first block is not. 


Use the other conditional-assembly directives (IFNE, IFEQ, IFLT, 
IFLE, IFGT, IFGE) in the same way that you use the DO directive. 
These directives are refered to as IFxx directives in the following 
discussion. A/ways follow them later in your source program by the 
FIN directive. 


The format of a conditional assembly block is: 


DO expression or IFxx expression 


( conditional block #1 ) 
[ ELSE 

( conditional block #2 ) ] 
FIN 


The DO or IFxx directives mark the beginning of a conditional 
block of source statements. When the Assembler encounters a DO 
or IFxx directive, it evaluates the operand expression and 
compares the result to the value zero. You must previously define 
in your source file any identifiers you use in this operand 
expression. 


The DO and IFxx directives control the assembly of a conditional 
block. Assembly of the statements in the block occurs when: 





Directive Resulting Expression 
DO <>0 

IFNE <= >If 

IFEQ =0 

IFLT <0 

IFLE <=0 

IFGT >0 

IFGE >=0 
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lf the value of the operand expression does not cause assembly of 
the block, the Assembler indicates the source statements it 
ignores by placing an S where the address is normally listed. 


lf you include an ELSE directive between a set of DO and FIN 
directives, you define the start of a second or alternate conditional 
assembly block. This alternate block is assembled only if the first 
conditional block is not assembled. The ELSE directive marks the 
end of the first block and the start of the alternate block. You can 
use an ELSE directive only within the range of a DO-FIN pair. 


The FIN directive marks the end of the entire conditional assembly 
block. When the Assembler encounters a FIN directive, it 
assembles all subsequent statements in your source file in a 
normal manner. 


The Assembler does not recognize assembly variables that you 
can change within your source program. However, you can use 
dummy identifiers that you define along with these conditional 
assembly directives to control a variety of different assembly 
conditions. 


This example demonstrates how you can use the conditional 
assembly. 


IFLE TBLSIZE-256 ' DOES TABLE FIT 
IN OHE FAGE? 
DS. 256 ' IF SO, USE 
OHE-FAGE TABLE 
ELSE ' OTHERPWISE 
OS Si2 : USE TWO-PAGE TABLE 
FIH ' EHD OF 


POMOITIOQWNAL BLOCK 


FAIL 


Form: FAIL pass,.string. 


You can use the FAIL directive in conjunction with the conditional 
assembly directives to provide a programmer error-message 
facility. When the Assembler encounters this directive while 
assembling your source file, it prints the message contained in the 
delimited string. Typically, you enclose the Fail directive inside a 
conditional assembly block that is assembled only when an error 
condition of some type is detected. 


Giving Directions to the Assembler 87 








The pass expression in the operand must be a number: 1, 2, or 3. 
This value is the Assembly pass number in which the Assembler 
prints the FAIL error message, with 3 meaning both pass 1 and 
pass 2 failed. The .string. is the message text; it must be enclosed 
within delimiters like an ASC operand. 


This directive is useful for automatically performing size checking 
on the matching halves of data tables, checking for code page 
alignment, and similar cross checks between things that must 
match in size or have particular relationships. You can use any of 
the conditional assembly directives with this FAIL directive to 
generate these automatic warnings. 





Source File Directives 


You can use the source file directives to control the source files 
that the Assembler assembles, and to control the size of the 
buffers that the Assembler uses to read these files. 


CHN 


Form: CHN filename{,[siot] [,[drive] [,vol]]] 


The Chain (CHN) directive is used to connect the segments of a 
large source program. The slot, drive, and volume expressions are 
optional; the filename is required. All statements following a CHN 
directive are ignored; use the CHN directive only as the last 
statement of a source file. If the filename that you include in the 
operand field of this assembly statement does not correspond to 
any file that exists on the indicated disk, the Assembler signals a 
FILE HOT FOUMO error and aborts the assembly. If you indicate 
the number of a nonexistent disk drive or an empty disk slot, the 
Assembler signals an |.) EF FOF message and aborts your 
assembly. 


If you use a volume parameter and you are using Disk II drives, the 
Assembler checks the volume number of the disk in the indicated 
drive. If the volume number doesn't match the one you specified, 
the Assembler prompts you for the correct volume. This feature 
lets you assemble large programs requiring multiple disks using 
only a two-drive system. The Assembler requires that one disk be 
available at all times to store the object file that it generates. 


To assemble multi-disk source files, you must have previously used 
the DOS INIT command to give your source disks different volume 
numbers. You can then use these volume numbers in the CHN or 
INCLUDE directives in your program source file. 
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INCLUDE 
Form: INCLUDE filename{,[slot] [,[drive] [,volume]]] 


The INCLUDE directive is used for one level of source file nesting. 
When the Assembler encounters this directive, it suspends 
assembling statements from the current source file and starts 
reading and assembling the statements in the file named in the 
operand field. Various errors are given if the file cannot be found. 
The Assembler prompts you to mount the proper volume if it 
detects a volume mismatch. This volume-switching arrangement is 
described in the section on the CHN directive. 


You cannot use an INCLUDE directive in an included file; that is, 
the Assembler does not permit nested include files. You also 
cannot use the INCLUDE directive in your source programs when 
you are using coresident assembly, that is, when the Assembler 
takes your source program from memory rather than from disk. 


SBUFSIZ and IBUFSIZ 


Form: IBUFSIZ expression 
SBUFSIZ expression 


These two directives let you optimize the size of the buffers the 
Assembler uses when reading your source and include files during 
assemblies. The default size of the source buffer is four pages or 
1024 bytes; that of the include buffer, 16 pages or 4096 bytes. 
These defaults are just about optimal for doing multi-file 
assemblies using include files with Disk || drives. 


The Assembler prints aFFEE SPACE PAGE COUMT message at 
the end of your assembly listing. This count is the number of 
memory pages that were not used by the Assembler for symbol 
and/or RLD tables at the end of your assembly. You can use this 
information in conjunction with the IBUFSIZ and SBUFSIZ 
directives to increase the size of the source and include buffers to 
speed printing and reduce assembly time. 


Be careful not to make the buffers too large when using Disk || 
drives; If you use a 32 page or larger buffer, the disk drive motor 
may timeout and stop spinning between disk reads, resulting in an 
assembly time that is actually slower. You can use larger buffers 
more effectively when you are using fast disks. 
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The Assembler evaluates the operand expression in two ways: 


è If the value is less than 128, the Assembler takes the value to be 
the size of the buffer in pages, where a page is 256 bytes. 


e If the value is greater than 256, the Assembler takes the value to 
be the size of the buffer in bytes. If the value is not divisible 
by 256, the Assembler truncates the buffer size to the nearest 
whole number of pages. 


If the resultant number of pages is greater than 127, the 
Assembler signals an ('".;EF FLL error. If the buffer size exceeds 
available memory, the assembly is aborted. This also happens 
when the new size of SBUFSIZ shrinks the source buffer, which 
contains the current source file, so small that the source file would 
be truncated. 


You can use these directives only within a source file; if you use 
them in an include file or in a macro definition file, the Assembler 
displays an IM\/ALIO FROM IHCLUDE -MACRO error. 


MACLIB 
Form: MACLIB [slot [,[drive] [,volume] ] ] 


The Assembler supports a simple macro capability with disk- 
based macros. Since the DOS 3.3 file structure does not have a 
library file type, macros can be supported only as individual files. 
This directive allows you to use the macro capability. If you attempt 
to use macros without the MACLIB directive, an IME HOWH 
JFCACE error message occurs for all macro references. In-line 
macros are not supported. 


The parameters are all optional, and if you do not supply any, 
macros are read from the first source file's slot, drive, and volume. 
Each macro must be a separate file in the catalog of the disk being 
used for macro storage. Assembling disk-based macros is slow, 
because the parameter-string substitution process requires 
scanning every character of the macro source. 


You can call macros by using a mnemonic that is not in the 
Assembler's mnemonic table. When the Assembler cannot find a 
match in its table, it then attempts to open a DOS text file with the 
mnemonic as the filename and the slot, drive, and volume 
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Detailed use of macros and arguments: 
see the section "Using Macros” in this 
chapter. 





parameters that you gave in the MACLIB directive. If the file does 
not exist, the assembly is aborted. When the text file is found, the 
source statements from the macro file are assembled using the 
argument strings to perform string substitution on the dummy 
arguments. 


Since the Assembler searches its mnemonic table first, you cannot 
use a macro name that is already the name of an existing 6502 
instruction mnemonic or an Assembly directive. Macro names 
must be both valid Assembler identifiers (that is, no space 
characters) and valid DOS 3.3 filenames. 





Controlling Your Assembly Listings 


You can use the directives and directive options described in this 
section to control the format and presentation of the assembly 
listings generated by the Assembler. These directives are entirely 
optional; you need not use any of them in your program source 
files to produce executable programs. Using them improves the 
quality of your printed assembly listings, and at the same time 
saves space in your program source files. 


You can include an identifier in the label field of any assembly 
statement containing a listing directive, but this is not 
recommended. Because assembly statements that contain listing 
directives are not printed in assembly listings, defining identifiers 
in this manner can result in incomplete documentation of your 
program. 


PAGE 
Form: PAGE 


You can use the Page directive to send an ASCII form feed 
character to the output device, thus causing a page eject. It also 
sends a blank line to the Apple II video screen. The Page directive 
itself does not print as a line on the listing, but its presence is 
shown by the action and the missing line number in the listing. 
When you are using the Editor, you can find this line by searching 
for the location of the missing line number. 
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LST 
Form: LST (ON , OFF) [, [NO]Joption [, [NO]option] ...] 


or 
LST [NO]option [, [NO]Joption] ...] 


where options are defined by the first letter shown: 
es 


Option Name 

Cyc Cycle times 

Gen Generated object code 
Warn Warnings 

Unasm Unassembied source 

Exp Expanded macro source 
Asym Alphabetic symbol table 
Vsym Value-ordered symbol tabie 
Sixup Sixup symbol table 


EE 


The Listing (LST) directive lets you suppress all or part of the 
source listing. Turning the listing off by using the LST OFF 
directive increases the speed of your assembly; this is most 
noticeable when you are doing a large assembly and listing it toa 
printer. You can use this directive any number of times to turn on 
and turn off selected parts of your program's listing. 


The options give you additional control of the information in the 
listing file. You can use any number of these options with or 
without the ON/OFF print control. You need to specify only the first 
letter of each option. If you do not use the LST directive in your 
source program or do not specify any options, the Assembler 
assumes that you want 


LST ON,NOCyc,NOGen, Warn, Unasm,Exp,Asym,NOVsym, 
NOSixup 
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The data directives: see the section 
“Generating Data in Your Object 
Code." 


Cycle Times 


Form: NOCyc (OFF) (default) 


The Cycle Times option lists the 6502 instruction cycle times for 
each assembly instruction in your source file. These times are 
printed in the listing as three extra columns just to the left of the 
source line numbers. The cycle time for each instruction is printed 
as a single digit within parentheses. 


The Assembler does not normally print instruction cycle times 
unless you specify the Cyc option. Typically, you do not want to 
have the cycle times printed unless you are programming timing- 
sensitive code. 


Generated Object Code 
Form: NOGen (OFF) (default) 


You can use the Gen option to control the printing of all the object 
code bytes generated by the data directives if this data requires 
more than one print line. This option does not affect what the data 
directives generate, only what they print. 


Unless you specify the Gen option, the Assembler normally lists 
only the first four bytes of object code generated by a data 
directive. The Assembler’s default state in NOGen, since this 
Saves printing time. 


Warnings 
Form: Warn (ON) (default) 


This option turns printing of Assembler warnings on or off. The 
Assembler normally prints all warnings it encounters as it 
assembles your file. You can suppress warnings by using the 
NOWarn option. The Assembler Prints a warning total, and also an 
error message total, at the end of the listing even if you use the 
NOWarn option. 


Giving Directions to the Assembler 93 





Unassemblied Source 


Form: Unasm (ON) (default) 


You can use the Unassembled Source option to suppress printing 
of statements in your program that are not assembled because 
they are contained in a conditional assembly block. Normally, the 
Assembler prints all the statements in your source program and 
marks those statements that are unassembled. 


Expanded Macro Source 
Form: Exp (ON) (default) 


You can control the printing of macro source statements using this 
option. The Assembler normally prints all the statements in a 
macro definition whenever it encounters a macro in your source 
program. Use the NOExpand opticn to suppress the printing of 
macro expansions. You can use this option within the macro 
definition itself if you want always to suppress this printing. This 
option does not affect macro operation in any way, just the 
printing of source statements in the listing file. 


Alphabetic Symbol Table 
Form: Asym (ON) (default) 


You can turn off the Assembler’s normal symbol-table-dump 
listing using the NOAsym option. The Assembler normally prints 
the symbol table in alphabetical order unless you disable it using 
the NOAsym option. 


Value-Ordered Symbol Table 
Form: NOVsym (ON) (default) 


If you select the Vsym option,the Assembler prints the symbol 
table by order of the symbol values. The Assembler requires an 
extra two bytes per symbol over the size of the symbol table at the 
end of pass 2 to complete this sucessfully. When the available 
memory is not sufficient, the Assembler uses what is available and 
prints only the symbols that it can sort. If you have a large 
assembly that uses up most of the 24K of symbol table space, the 
value-ordered symbol table may not contain all the identifiers. 
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Sixup Symbol Dump 


Form: NOSixup (OFF) (default) 


When you direct the listing to a printer, this option causes the 
symbol table dump to be printed in six columns, instead of the 
normal four. This assumes that your printer can print 120 or more 
characters per line. The four-column default results in a table that 
is 80 characters wide. 


REP 


Form: REP expression 


You can use the Repeat (REP) directive to print a string of 
characters in your listings, starting at the first character of the 
source statement portion of the listing. The default character that 
is printed is the asterisk ( * ): you can change this character by 
using the CHR directive. You can use any number of REP 
directives in your source file. 


You use this directive to print a string of asterisks to set off 
comment headings at the beginning of subroutines or modules, or 
otherwise to make your listings more readable. By using this 
directive instead of simply inserting the string of asterisks in your 
file, you can save considerable space in your source file. 


Only the low byte of the expression is used. You can specify that 
from one to 256 of the currently defined CHR’s are to be printed. If 
you specify 0 or 256, 256 characters will be printed. 


CHR 
Form: CHR /? 


Use the Character (CHR) directive to change the character 
repeated by the REP directive. 


The ? represents the character you want to see printed by the REP 
directive. You must precede this character by a delimiter, shown 
here as a slash. Both the printed character and the delimiter can 
be any character. The CHR directive can be used any number of 
times in your source file to change the printed character in 
different parts of your listing. 
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SKP 
Form: SKP expression 


The Skip (SKP) directive lets you insert a number of blank lines in 
the listing by sending ASCII carriage returns to the output device. 
The device must provide its own line feed after a carriage return if 
the device requires a line feed to advance a print line on the paper. 


SBTL 
Form: SBTL .string. 


The Subtitle (SBTL) directive lets you place a title line (specified by 
the delimited string shown above as -string.) at the top of each 
page of the listing file. Using SBTL is optional, but it provides a 
means of identifying a specific listing. 


When you use this directive, the first line of each page contains the 
current subtitle followed by the Assembler ID Stamp, which is the 
date followed by a six-digit integer. The Assembler prints blanks in 
the title line if the ASMIDSTAMP file is not available for an 
assembly. 


Using Macros in Your 
Assembly-Language Programs 


The MACLIB directive described in the section ‘‘Source File 
Directives” lets you use the disk-based macro capability of the 
Assembler. The Assembler supports macro definitions that you 
create prior to the assembly and store on a disk as a separate DOS 
text file. You cannot define macros within your program source file. 


When you use the MACLIB directive in your program source file, 
you tell the Assembler that you may use macros later in this file. 
The MACLIB directive also tells the Assembler on which disk the 
macro definitions are stored. After you use the MACLIB directive, 
the Assembler assumes that any mnemonic you use in your source 
file that is not a standard 6502 instruction or Assembly directive 
mnemonic is the name of a macro definition that resides on this 
disk. 
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Calling Macros in Your Program Source File 


To call a macro in your program source file, include the name of 
the macro in the mnemonic field of an assembly statement, just as 
you would use any other mnemonic. This macro name must be the 
name of the DOS text file that resides on the disk volume you 
specified in your earlier MACLIB directive. You can include 
operand expressions in the operand field of these assembly 
Statements, but you cannot include a comment. 


When the Assembler encounters a mnemonic that does not match 
either a standard 6502 instruction, SWEET 16 mnemonic, or 
Assembly directive, the Assembler suspends its assembly of the 
current source file, preserves any necessary information, and 
attempts to read a file from the macro source disk having the 
mnemonic name as the filename. If this macro definition file 
doesn't exist, the Assembler Signals the error and aborts the 
assembly. 


The Macro Definition File 


The macro definition file is a text file consisting of regular 6502 
assembly statements. There are no special macro directives that 
you must use in defining a macro. 


When you call a macro in your program source file, you can specify 
up to nine string parameters in the operand field of the statement 
containing the macro name. You must separate each of these 
String parameters by a comma. The Assembler parses this 
operand field using the comma as a delimiter and substitutes 
these string parameters into your macro definition wherever you 
indicated. Two commas with no characters in-between are 
assumed to represent a null parameter. You cannot pass a comma 
as part of a string parameter except as a numeric constant, that is, 
as $2C or $AC. 


In the macro definition file that you created on the macro source 
disk, you can indicate where these String parameters are to be 
substituted by using the two-character sequences & 1 through &9. 
The Assembler replaces these sequences with the characters of 
the first through ninth string parameters, respectively. If you 
reference a parameter in your macro definition that you did not 
supply when you called the macro in your source file, the 
Assembler replaces that parameter with zero (no) characters. You 
can use any number of &n parameters within a macro statement or 
within a single field of a statement. 
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An example of a macro definition is: 


LCA a Í 

a N 

AC ee 
STA a 
LCA i +l 
ACIC: wati 
STA he 3 +1 


If you save this example macro definition in a file with the name 
ADD 16, you can call the macro as shown: 


MACLIE | ENABLE MACROS 
WALL Ertl FRA 
WALLS Ertl FFE 
SLI Emu FFL 


IHVOERE ADOLE MACRO BELOW 
AOS WALUL, VALU, Sue 


When you assemble this source program, the Assembler expands 
this macro and substitutes the three parameters into the macro 
definition where you indicated. This macro expansion appears in 
your assembly listings as: 


1 MACLIE : EWRELE MACROS 
2 WALII EHI FA 
3 WAL Evil $FE 
4 SIM Eri $F I 


RRR KKEKEEKEK 


14 IHVOKE AOOLE MACRO BELOW 

11 AOOLEe WALL, VALIZ, SUM 
1+ LOA WALLY 

= + ie 

a+ ACI WALLS 

4+ STA SLIM 

= + LCA WALIJI +1 

E+ AO WALLS +1 

r+ ZTA SLIP +1 
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The &0 parameter represents the 
number of parameters that are present 
in the assembly statement Calling a 
macro. 


The Assembler always lists the macro expansion following the 
assembly statement that calls the macro (line 11). The lines of a 
macro are indicated in the assembly listing by the plus character 
following the line number. You can suppress the expansion of a 
macro by using the LST NOEXP directive described in the section 
“Controlling Your Assembly Listings.” 


Notice that the Assembler Substituted the &1 argument with the 
first string parameter. VALU1, and so on for all of the macro 
Parameters. The process of Substituting macro Parameters must 
not produce an assembly statement longer than 255 characters. 
This can happen if you attempt to insert a large number of long 
String parameters into a long macro statement. If you use a macro 
Statement with a long comment field, you may also encounter this 
problem. 

í 
Warning 
Do not place a comment after a macro string parameter. If you do, the 


Assembler tries to assemble the comment. 


The Assembler supports two special features to help you use 
macros. These features are the &0 and &X parameters. The 
following Paragraphs describe how you can use these parameters 
inside your macro definitions. 


The &0 Parameter 


You can use the &0 parameter in your macro definition to 
represent the number of parameters that are present in the 
assembly statement that calls this macro. The Assembler always 
counts the number of parameters present in the operand field of 
the statement calling the macro. It then substitutes this single-digit 
number wherever it finds the &0 Parameter in your macro 
definition. 


You can use this &0 Parameter within a conditional assembly 


Statement in your macro definition, either to validate the macro 
call or to create flexible macro definitions. 
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The &X parameter represents the 
number of times macros are used 
during the assembly. It is useful for 
generating unique identifiers within a 
macro definition. 
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The &X Parameter 


You can use the &X parameter (a/ways uppercase X) in your macro 
definitions to represent a cumulative count of the number of times 
that you used any macro during this assembly. The Assembler 
substitutes a one- to four-digit numeric string for each occurrence 
of the &X parameter, starting initially with the string 1, and 
increasing this number by one each time you call a macro during 
your assembly. 


The &X parameter lets you automatically generate unique labels 
within a macro expansion, even if you call the macro definition 
many times. All the labels you generate using the &X parameter 
appear as individual entries in the symbol table and all appear in 
the symbol table dump. 


You can use the &X parameter in your macro definition by 
appending it to some label prefix or embedding it inside a label, as 
shown in this example: 


1 UDT #3 

2 F&nL STR &1i,Y 
3 DUETY 

4 BHE F&xL 


This example shows &X embedded in a label. The Assembler will 
create the unique labels F1L, F2L, and F29L when this macro is 
used as the first, second and twenty-ninth macros of an assembly. 
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Using the Single-Step and Trace Modes 

Single-Stepping Your Program 

Using Trace Mode 

Tracing Subroutines 

Setting Transparent Breakpoints 

Using Breakpoints 

Clearing Transparent Breakpoints 

Adjusting the Trace Rate 

Using Display Options in Trace and Single-Step Mode 
Using Execution Mode 

Setting Real Breakpoints 

Debugging Your Program in Execution Mode 
Debugging Real-Time Code 
Debugging Programs that Use the Keyboard and Display 

Eliminating Screen Contention 

Eliminating Keyboard Contention 

Using Hand Control 0 to Control Trace Mode 

Using Hand Control 0 
Executing Undefined Opcodes 








The process of testing and changing a 
program to eliminate errors is called 
debugging. 
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Every assembly-language programmer eventually runs up against 
a newly-written or revised program that just doesn't work as 
intended. This isn't any reflection on you as a programmer; 
everyone occasionally overlooks a problem condition or omits an 
essential instruction, resulting in a program bug. 


The origin of the term bug, meaning a computer error, can be traced 
back to the origin of computers themselves. 


According to U.S. Navy Captain Grace Murray Hopper, a pioneer in 
computer technology during Worid War li, the first computer bug was 
discovered at Harvard in August 1945. Hopper, interviewed at age 74, 
recalled that at the time she and her associates were working on the 
Mark |, which she affectionately called “the granddaddy of today’s 
computers:” 


‘Things were going badly; there was something wrong in one of 
the circuits of the long, glass-enclosed computer. Finally, 
someone located the trouble spot and, using ordinary tweezers, 
removed the problem—a two-inch moth. From then on, when 
anything went wrong with a computer, we said it had bugs in it.” 


A real test of your programming skill is how quickly you can locate 
problems in your programs and fix any errors to produce a working 
program. With the proper tools, this process of testing and fixing 

your program is easy and efficient, allowing you to produce error- 
free quality software. 


The Bugbyter program is a display-oriented debugging tool that 
can save you considerable time in testing and debugging your 
assembly-language programs. Using Bugbyter for just a few 
minutes, you can see precisely how your program is executing and 
where things are going wrong. The Bugbyter program is also a 
useful tool for testing and verifying a working program to make 
sure that it operates correctly under a variety of conditions. 
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Bugbyter functions and commands: see 
Appendix C. 


This ability to relocate Bugbyter is 
discussed later in this chapter. 
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This chapter describes how you can use Bugbyter to test and 
debug your assembly-language programs: 


è it describes the characteristics of the Bugbyter program and 
how Bugbyter can help you to debug your programs. 


è it contains a brief tutorial on using Bugbyter to test the 
assembly-language program you created in the tutorials in 
Chapters 2 and 3. 


è it describes how you can use all Bugbyter’s features while 
testing and debugging your programs. 


Introduction to Bugbyter 


The Bugbyter program lets you load and control the execution of 
your assembly-language program on any Apple || system. You can 
use Bugbyter to test and debug almost any assembly-language 
program as long as your program leaves enough storage space to 
hold the Bugbyter program somewhere in your Apple II's memory. 
The Bugbyter program can be loaded and executed almost 
anywhere in memory, allowing you the greatest flexibility in 
debugging your assembly-language programs. 


Bugbyter gives you a variety of options to use when debugging 
your 6502 assembly-language programs. At any time you can view 
the status of the 6502 registers, stack, and memory as they appear 
to your assembly-language program. When you are debugging 
internal portions of your program and do not need to view your 
programmed displays, you can use Bugbyter’s Master Display to 
show you 


@ all of the Apple Il’s 6502 internal registers 
è a portion of the Apple |l's program stack 


e amnemonic disassembly of portions of your assembly-language 
program 


è portions of your computer's memory 


è any real or transparent breakpoints that you set. 
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The section ‘‘Relocating the Bugbyter 
Program” in this chapter explains how 
to relocate Bugbyter to prevent 
conflicts with your own program. 


Using Bugbyter, you can step through your program one 
instruction at a time, observing all the effects of executing each 
instruction. If you want, you can alter the layout of Bugbyter’s 
Master Display to show you more or fewer stack or memory 
locations, program statements, or breakpoints. 


At any time, you can change the conditions under which you are 
testing or debugging your program. For example, you can 


@ change the contents of any 6502 register; 


è alter the contents of memory locations or the stack to change 
data values that may be stored there; 


è alter instructions or parts of your program and immediately test 
these revisions. 


To fix or change quickly the 6502 assembly-language instructions 
that comprise your program, you can enter 6502 assembly- 
language mnemonics directly into your Apple II's memory. 
Bugbyter translates these instructions and stores the actual 
machine codes into the memory locations that you select. 


You can indicate to Bugbyter regions of code that must execute in 
real-time. This lets you test programs that make use of some of the 
Apple II's real-time operating system routines, and also test your 
own programs that contain portions that must execute in real- 
time. Bugbyter tests these programs using all its debugging 
facilities, while still allowing execution at full speed. 





Restrictions on Using Bugbyter 


You can use Bugbyter to test and debug any assembly-language 
program as long as your own program leaves a contiguous block 
of memory 6700 ($1A00) bytes long somewhere in your Apple II's 
memory. This memory is needed to contain the Bugbyter program 
code and data areas. Bugbyter also uses the first 32 ($20) bytes of 
the Apple II's stack (memory locations $100 to $11F); this should 
not cause problems unless your own program alters the contents 
of the beginning of the stack. 
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Allowing for these memory restrictions, there are 
that you cannot use Bugbyter to test and debug. 
your Apple lle system use bank-switching to exte 
memory, Bugbyter must remain resident in memc 
Although you can debug programs that use bank 
cannot swap Bugbyter out of usable memory spa 
debugging. 


Ms A Tutorial: Using Bugbyter 


In the tutorial that follows, you use Bugbyter to te 
of the short program you created and assembled 
Chapters 2 and 3. It shows you how to test an as: 
program to verify that it works as you intended an 
how to modify your programs so they execute dif 
To work through this tutorial, you need 

e your Apple |i system 


è the DOS Programmer's Tool Kit Volume II disk 
Bugbyter program and your TESTPROGRAM.( 
that you created in the tutorial in Chapter 3. 
In this tutorial, you will 
è become familiar with Bugbyter’s Master displa 
e load your assembly-language object program f 
e test your program using the Single-Step and Trace modes: 


e change your program and test it again. 
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Figure 4-1. Bugbyter’s Master Display 


Register subdisplay: 6502 and 
Bugbyter registers 


@6502 Stack with Stack Pointer 
highlighted 


@cCode Disassembly display 
@Memory Cell subdisplay 
®Breakpoint subdisplay 
®@Bugbyter Command Line 


Your screen may appear with slight 
differences. 








Getting Started 





What You Do What Happens 
1. Insert the DOS Your Apple |i loads the 
Programmer's Tool Kit Bugbyter program. 


Volume II disk into your disk 
drive 1 and turn on your 
Apple II. After your Apple II 
loads the operating system 
from the disk and displays the 
Applesoft prompt (]), type 


ERIH BUGE TER 
and press (RETURN). 





Bugbyter then shows you its Master Display on your video screen. 
This Master Display is divided into six subdisplays (Figure 4-1). 


C R B PC A X Y S P_ NV-BDIZC|a 
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POINT COUNT TRIG i 
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86660 6680 886060 ABHA 
8688 
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Figure 4-2. The Register Subdisplay 
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The Register Subdisplay 


The six 6502 registers and three Bugbyter registers are shown in 
the Register subdisplay at the top of the screen (Figure 4-2). 







c R 6 PC A X 
gana 8 0 8808 oO ğü ği 12 papag 





t a4 


Ec 
eo: F 


AGAD: L BF POINT COUNT TRIG e@RORE 
HHA: 46 L l ARAD SESE Se SESE Wome 
WAM: 40 L 2 yoo ESE eS) wee SE SES 
HAAA: se L 3 AAG eee Wee SESESEY) 
BHAA: 40 L 4 SISSI) Woe ARAA AAA 

C> 132323 COMPUTER-ADVANCED IGEAS ‘1.11 
eS 


The 6502 registers are: 


6502 Register Name 

PC Program Counter 

À A-Register 

X X-Register 

Y Y-Register 

S Stack Pointer 

P Processor Status Register 


The display in the upper-right corner shows the Processor Status 
Register in both two-digit hexadecimal (P) and in binary (NV- 
BDIZC) notation, where the individual flags are: 





Flag Name 
N Negative 
V Overflow 
B Break 
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Figure 4-3. The Stack Subdisplay 





Flag Name 


D Decimal 
| Interrupt 
Z Zero 

C Carry 





The Bugbyter registers in the upper-left corner of the display are 
explained later in this chapter; they are: 





Bugbyter Registers Name 


C Cycle Count 
R Trace Rate 
B Breakpoint Flag 





The breakpoint flag is either O (out) or | (in). 


The Stack Subdisplay 


Bugbyter’s Stack subdisplay (Figure 4-3) acts as a window into the 
6502 memory stack. The Stack subdisplay contains the ascending 
addresses of memory locations just before and after the location 
pointed to by the Stack Pointer, and thus shows the contents of 
each byte in a portion of the stack. 





















ita: Dl 
IPA: Fi Bia. D Se ko Cane eee 
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ire: Gl 
lem: 0i 
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IFF: 37 
1460: FF 
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iwc: FP 
bas: FF 
aa -, {90:40 L EF POINT COUNT TRIG BPOFE 
1 a: F F ee L l ADA SESE eS SESE SES SISESE 
JAHH: 4T L 2 90900 0000 90090 good 
HAAA: AE L x SISESE AAA Cee SEAIS 
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Figure 4-4, The Code Disassembly 
Subdisplay 


Bugbyter display options: see the 
section on Trace mode. 
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The line in this subdisplay that represents the current location of 
the 6502 Stack Pointer is always highlighted. 
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The Code Disassembly Subdisplay 


To the right of the Stack subdisplay, the screen shows the Code 
Disassembly subdisplay. Bugbyter uses this window to show a 
disassembly of your program's code using standard 6502 
assembly mnemonics and address mode syntax. 


Although this subdisplay is currently blank, Figure 4-4 shows an 
example of how the Disassembly subdisplay might look. 


In the example shown, the first line of the Disassembly subdisplay 
is: 


leew; LOY #08 Ae Ce 


In this line of the subdisplay the items are: 


aag The address of the instruction 

Sayi the 6502 instruction mnemonic 

#ECG an example of the instruction operand 

Aa Ce the actual machine-instruction bytes in memory 


These machine-instruction bytes (AO CO) are displayed as one of 
Bugbyter’s information display options. As you trace or single-step 
through your program, you can select one of seven display options. 
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MEM command: see the section 
“Viewing and Altering Memory.” 


Figure 4-5. The Memory Cell 
Subdisplay 


Breakpoints and other techniques that 
you can use in debugging: see the 
section ‘Controlling the Execution of 
Your Program.” 


Figure 4-6. The Breakpoint Subdisplay 


The Memory Cell Subdisplay 


The Memory Cell subdisplay (Figure 4-5) shows the contents of a 
number of memory locations that may be important to your 
program. You can use the MEM command to select the addresses 
of individual bytes or byte-pairs that Bugbyter displays 
continuously in this portion of the Master Dispiay. 
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The Breakpoint Subdisplay 


Bugbyter allows you to set a number of program breakpoints that 
you can use to control the execution of your program. The 
Breakpoint subdisplay area (Figure 4-6) of the Master Display, just 
below the Code Disassembly subdisplay, shows these breakpoints 
and relevant breakpoint information. 
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The Bugbyter Command Line 


On the last line of the display, you see the Bugbyter command line, 
which currently shows a brief copyright notice. The blinking cursor 
just after the colon (:) prompt indicates that Bugbyter is ready to 
accept commands from you. 


Figure 4-7. Bugbyter Command Line 
Allows You Access to All Features 





When you first start up the Bugbyter program, you are placed at 
The Bugbyter command line is the last the Bugbyter command level. From this level, you can access all 
line on the Master Display screen. Bugbyter’s features by typing short commands on the command 
line. You can also use commands to enter one of Bugbyter’s three 
debugging modes to access more features. Figure 4-7 shows the 
five Bugbyter modes and the things that you can do in each mode. 
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The things you can do at the Bugbyter command level are: 


In 
a 


In 


execute DOS commands, such as BLOADing programs 


view or alter contents of memory by entering hexadecimal (hex) 
values, character codes, or 6502 assembly code 


change the contents of the 6502 or Bugbyter registers 

enter Applesoft/DOS or the Monitor 

alter the layout of the Bugbyter Master Display 

set and clear breakpoints 

view areas of memory, using Bugbyter’s Memory Page Display 


enter one of Bugbyter’s three debugging modes. 


Memory Page Display mode you can 

view areas of memory; 

alter contents of memory by entering hexadecimal values, 
character codes, or 6502 assembly code. 

Single-Step mode you can 

single-step or execute your program one instruction at a time; 
view Bugbyter’s Master Display, or view your Apple II's low- 
resolution, high-resolution, or normal text screens. 

Bugbyter Trace mode you can 


trace your program's execution, updating Bugbyter’s Master 
Display after each instruction, scanning for RTS opcodes or 
transparent breakpoints; 


view Bugbyter’s Master Display, or your Apple Il’s low- 
resolution, high-resolution, or normal text screens. 


In Bugbyter Execution mode you can 


execute your program directly on the 6502, using real 
breakpoints to control execution. 
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Typing Bugbyter Commands 


When you type commands at the Bugbyter command level, you 
simply type the characters to form the command and press 
when you are done. If you make a mistake when typing, 
you can use to move the cursor back and then retype the 
proper characters. To erase the line and start retyping it again, 


press (CONTROL)-(X). 


Bugbyter also has some additionai editing commands to save you 
from retyping. If you type a line of characters on the Bugbyter 
command line and notice an incorrect character earlier on the line, 
you can use (—)and (>) to place the cursor over the incorrect 
characters. Then 


è to replace the character, type a new character over the old one. 


e to delete the character altogether, press (CONTROL)-(D). 


e to insert additional characters before the current character. 
press (CONTROL)-(7 ) and type the additional characters; to end 
the insertion press (—), (©), or (RETURN). 

e to enter a control character on the command line, if you want to 


store character-string information into memory, press 
(CONTROL )-(C) before the entering the control character. 


e to move the cursor to the beginning of the command line, press 


(CONTROL )-(B ). 
e to move to the end of the line, press [CONTROL )-(N ). 


When you finish editing the line, press (RETURN). When you press 
(RETURN), Bugbyter accepts all the characters on the command 
line. If there are unwanted characters to the right of the cursor, 
delete them by pressing (CONTROL)-(0) or replace them with 
spaces by pressing (SPACE). 
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Table 4-1. Bugbyter Command-Line 
Editing Functions 


To call a DOS command while using 
Bugbyter, type a period (.) before you 
type the DOS command. 





Table 4-1isa summary of the editing functions and the keystrokes 
that accomplish them. 


Editing Function Keystroke 

Move cursor /eft one character 

Move cursor right one character 

Move cursor to beginning of line 

Move cursor to end of line (CONTROL)-(N) 

Delete entire line (CONTROL)-(X) 

Delete current character (CONTROL)-(D) 

Insert characters (CONTROL)-(1 ) 

Enter a control character (CONTROL)(C), any character 
Accept the current line 


ee 


Loading Your Program 


To debug your program using Bugbyter, you must first load your 
Program into memory by using the regular DOS BLOAD command. 


By the Way: When you enter a DOS command, the Bugbyter screen 
display scrolls up and leaves the cursor below the last line of text. 


Press to restore the Bugbyter display. 


1. Type After your Apple |! finishes 
bai loading your 
ELQAC 
TESTPROGRAM, DEJO TESTPROGRAM.OBJO 
program into memory, you see 


and press (RETURN). the blinking cursor. 
TESTPROGRAM.OBJO is the 

binary file you created in 

Chapter 3. 





Note: Any DOS errors that occur when you execute a DOS command 
from within Bugbyter leave you at the BASIC command level. To return 


to Bugbyter, press (RESET), then type 

CALL 1816 
and press (RETURN). You return to Bugbyter and see Bugbyter’s Master 
Display. 


If you later run Bugbyter in a Language Card, DOS errors leave you in 
the Monitor. If this happens, press and then 


to return to Bugbyter. 
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2. To return to Bugbyter’s 
Master Display, press (RETURN). 





3. To view your program that Bugbyfter fills the Disassembly 


you just loaded into memory, portion of your screen with the 
type first few instructions of your 


Lanal 


and press (RETURN). 


The Bugbyter L command loads the 
Code Disassembly subdisplay with the 
next several instructions following the 
address you specify. 


it on the screen. 


C kF B PC A X x $ NV-BOIZC 
8000 66 0 HHGG HÖ AÖ üü FF aaeeaneie 
1F9;: Cl 1964; LOY #$CA Aa Ce 
iFA: Fl 1902: LOX #$00 AZ 86 
IFB: @@ 1664; JSR $1000 2@ øD 
LEC» 04 1007: INX ES 
1FD: @1 1068: CPX #$05 EG 85 
1FE: 30 100A: BNE $1004 D FS 
1FF; 37 100C: RTS 6a 
106; FF 1000: INY cs 
1601: FF 100E: TA ag 
102: FF 1060F: STA $1160,» 30 1 
163; FF 1012: RTS 6a 
164; FF 1@13; BRK Be 
145; FF 1014: BRK ae 
6o900:4C L BP POINT COUNT TRIG BROKE 
@660;40 L 1 6060 GGG 86600 8606 
6660:40 L 2 60600 8868 8666 86866 
@60@0;4C L 3 A686 8666 8660 8686 
@90@0;4C L 4 600 8800 8606 86860 
E.: 
You may see different values in the You can now visually check the instructions in your program to 


Stack subdisplay; this is normaland not verify that your program was assembled correctly (in the tutorial in 


cause for alarm. 


Chapter 3). 
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program, starting with the 
instruction at address $1000. 





Since TESTPROGRAM.OB4JO is a short program, you can see all of 





The S command places Bugbyter in 


Single-Step mode. 








Single-Stepping Through Your Program 


Bugbyter allows you to watch the execution of your program one 
instruction at a time, letting you see the results after each 
instruction. 





1. To begin single-stepping your The LDY instruction that 
program at address $1000, appears at address $1000 is 
type highlighted, and the program 
counter (PC) on the top line of 


HAS 
Lagas the screen shows the address 


1000. 
and press (RETURN). o 

a R B PL A x + S P NV-BOI2C 
564408 88 Ü 1466 86 66 ÖÖ FF 62 8866006186 

1FS: Cl 

1FA: Fl 

1FB:;: 6@ 

1FC: 01 

IFO: @1 

1FE: 9D 

1FF: 37 

196; FF 

161: FF 

102: FF 

1603: FF 1648; LOY ##C8 

184; FF 1862: LD% #$6@a 

195: FF 1664: JSR $1080 
HH08;4C0 L BF POINT COUNT TRIG BROKE 
HAHA: 4C L 1 8486 84866060 8660 48666 
DAA: 4C L 2 BABE 6980 8800 498986 
9008@;:;4C0 L 3 8668 OGHA 88686050 48688 
BODA: 4E L 4 56466 88000 86086 8886 
SINGLE STEP 





Note that no instructions of your program are executed and none 
of the registers are changed except the PC register. The first 
instruction of your program to be executed is to load the Y-register 
with the value $CO, as indicated by the highlighted LDY instruction 
on the Master Display. 
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Pressing in Single-Step mode 2. To execute this LDY Bugbyter executes this 
executes the next instruction. instruction, press (SPACE). instruction of your program and 
updates the display. 


E . 


€ R U PG iui eae P NY-BDIZC 
8208 66 O 1082 66 BÖ CB FF BØ 10110000 


iF9: Cl 
1FA: Fl 
1FB: 86 
IFC: Bi 
1FD: 0i 
1FE: 30 
LFF: 3? 
106: FF 
101: FF 
102: FF 186600: LOY #$CB P;:;1811806 
103: FF 1002: LOX #88 
164; FF 1664: JSR $1000 
105: FF 1867: INX 
6808;4C P POINT COUNT TRIG BROKE 


8860 8668 
9606 86800 86000 48004 
6060 8800 6806 #8028 


© 
© 
© 
© 
po 
oO 
rt Fae 
GaN ow 
© 
® 
® 
& 
© 
© 
Pex 
© 


2000 66060 8800 48808 rf 


SINGLE STEP 


Notice that the program counter is incremented to 1002 and the Y- 
register is loaded with the hex value CO. In the Disassembly 
subdisplay, the disassembied instructions are shifted and the 
instruction at address 1002, the next instruction to be executed, is 
now highlighted. Bugbyter also displays the contents of the 
processor status register in binary to the right of the instruction 
that was just executed. 


The next highlighted instruction loads the X-register with the 
value $00. 
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we eee ee 


3. Press to execute this Verify that the X-register now 


instruction. contains the value $00. 

a R § pe A x yg p NY -B0IZC 
9528 48 0 1004 J9 96 cø FF 32 88116819 

1F9: ¢€1 

1FA: Fi 

1FB: oa 

IFC: ği 

IFD; ðt 

1FE: 30 

LFF: 37 

190; FF 

101; FF 1869: LOY #$C9 P:19118909 

162; FF 1962: LOX #$0ğ P:38119819 

193; FF 1484; JSF £1440 

194: FF 1907: INY 

195; FF 1002: CPX #305 
B880:4C L BP POINT COUNT TRIG BROKE 
AvA: 4C L 1 8656 8868 95995 ğøøğø 
B8888:4c L 2 8805 8800 9000 ga09 
688B8:4ce L 3 8648 AGOA 9058 98900 
9600:40 L 4 8684 9886 88868 968886 


SINGLE STEP 


a ee 


The next instruction is a jump-to-subroutine instruction that calls 
the Store subroutine at address 100D. This JSR instruction 
changes the contents of the stack pointer as weil as the program 
counter. 


4. Press to execute this Bugbyter executes this 

instruction. instruction and calls the 
Subroutine at 100D. Notice that 
the program counter (PC) 
contains the address 100D. 


Notice that the stack pointer (S) changed to FD and that the stack 
Subdisplay shifted down. The stack pointer points to the location 
identified by the highlighted bar. 
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Pressing (ESCAPE) while in Single-Step 
mode returns you to the Bugbyter 
command level. 


The MEM command lets you modify the 
Memory subdisplay. 
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wn eee E 


. 
a D 


G Re 6 PC kt YY S p NY=BOTZC 
gae0 AG O 1880 gð 98 CB FD 32 991188128 
1F7: 43 
1-3; D4 
1F9; C1 
1FA: Fl 
1FB: 38 
1FC: Oi 
1FO:;: 51 
IFE: 86 1000: LOY #$C9 P:;181199a9 
1FF: 18 102: LOX #389 P: 001160919 
100: FF 1ga¢;: JSR $1990 P:99118019 
181: FF 1ge@o: IHY 
182: FF LOE: TYA 
193; FF 1920F: STA $1180,% 
aga@;4C P POINT COUNT TRIG BROKE 


gaga aga 32899 AAAA 
pappa 9900 3299 9898 
apaa AAAA AAA AAAA 
aAA 8809 JAHA AGNA 


D 

© 

5D 

a p 

oO 
AEAN 
Gifu @ 


SINGLE STEP 


apa ee n 
5. Execute the next two These instructions increment 
instructions by pressing the contents of the Y-register 
twice, once for each instruction. and transfer the contents of the 
Y-register to the A-register, 
respectively. You can verify the 
operation of these instructions 
by watching the Register 
subdisplay. 


spr atten Ae SOS ae 


Using the Memory Subdisplay 


The next instruction to be executed is STA $1100,X; this stores the 
value in the A-register into memory address $1100 (if you press 
right now, you will execute this instruction and store the 
value $C1 into memory). Before you execute this instruction, use 
the Memory subdisplay to verify that the proper value gets stored 


in memory. 


eee arrestee aaa ema 
1. Press to exit from You see the colon prompt and 
Bugbyter’s Single-Step mode blinking cursor of the Bugbyter 
and return to the command command level. 
level. 
2. Type The blinking cursor appears in 
the first position of the Memory 
MEM i 
subdisplay. 


and press (RETURN). 


SAAE EEEE aa 
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Each cell of the Memory subdisplay consists of an address, 
followed by a colon and the hex value of the byte stored in that 
memory location. After the hex value is its corresponding Apple 
character. 


c R B PC A kX Y $ P. NV=-BOIZC 
20906 260 0 1000F C1 Ø Ci FD BH 1811896808 
1F7: 43 
1F3: O4 
149; ct 
1FA: Fi 
1FB: 388 
1FC; Bt 1986: LOY #809 P:1011090600 
LFO: wl 19862: LOX #388 P:98119898019 
1FE: 66 1964; JSR $1880 P:86118961%8 
1FF: 18 1000: INY P:181180090 
19@; FF 100E: TYA P:18119626 
191: FF LAAF: STA $1188, # 
192: FF 19812: RTS 
183: FF 19813: BRK 
9@@0:4C L BP POINT COUNT TRIG BROKE 
940@:4C L 1 8880 896800 308600 46908 
9860;:4C L 2 8686 8880 6883 93088 
8606:4C L 3 8488 8880 AOA 4045 
Bea6a:4C L 4 848080 860956 988680 8688 





3. To set a particular memory The address 1100 appears in 
address in this first memory the first memory cell of the 
cell, type Memory subdisplay, followed by 
1148 the byte currently stored in that 
al memory location. The blinking 


cursor moves to the next 
and press (RETURN). 





memory cell. 
4. To enter the addresses of the You loaded the addresses of 
next four memory locations, five consecutive memory 
type locations into the Memory 


1161 subdisplay. (As you later 

i execute your test program, your 
1182 program will fill each of these 
memory locations with an Appie 
character code.) 


Press after you type 
each address. 
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Pressing (ESCAPE J always returns you 


to the Bugbyter command level. 











5. If you make a mistake typing 
the addresses, don’t worry; just 


press to move the 
blinking cursor to the memory 
cell with the address you want 
to change and type the new 


address over the old. When you 


are done, press (ESCAPE) to 


return to the Bugbyter 
command level. 





6. To return to Single-Step 
mode and execute the next 


instruction, type 


= 
‘ 
ba} 
. 
= 


at the command level and press 


RETUAN J. 
C Re B PC 
9908 980 1812 
1F7: 43 
1F8: D4 
1F9: ÇI 
1FA: Fil 
1FB: 20 1308 
1FC:;: @1 1482 
1FO;: 1 Lage 
1FE: 86 1980 
1FF: 19 100E 
196: FF 18a 
181; FF Lat 
192: FF 131 
193: FF 141 
1100:71 A BP 
1191:96 @ 1 
1192:00 a 2 
1193:90 @ 3 
1104:80ġ0 ü 4 
SINGLE STEP 


A s 


Cl 20 


LOY 


JSR 
INY 
TYA 
STA 
RTS 
BRK 
BRK 


POINT 
828488 
38908 
8098 
8899 


Bugbyter executes the next 
instruction of your program, 
storing the value $C1 into the 
memory location $1100. You 
can verify that this value 
actually was stored by looking 
at the vaiue shown in the 
Memory subdisplay for that 
address. 


Y S PF. WW-BOtEC 
Ci FO BO 18119806 


#¢02 P: 18118898 
#398 P: 098119819 
$1300 P:48118019 
P; 181198960 
P:19118009 
$1188,% P;18119868 


COUNT TRIG BROKE 
9898 AAAA 49868 
8885 8808 8808 
8999 8608 8888 
8404 986060 3948 
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Tracing Your Program 


To make sure that the rest of your program operates as it should, 
trace the remainder, rather than single-stepping through it. When 
Bugbyter traces your program, it updates the Master Display after 
executing each instruction. You can watch your program fill the 
memory locations $1101 through $1104 with the codes for the 
characters 8 through £. 


Pressing from Single-Step 1. To trace the remainder of You should see the words 

mode places you in Trace mode. your program, press SINGLE STEP on the Bugbyter 
while you are in Single-Step command line before you press 
mode. (RETURN). After you press 


(RETURN), Bugbyter replaces this 
with the word TRACE for Trace 


mode. 
rete 


Bugbyter traces the rest of your program, executing each 
instruction in turn. When Bugbyter finishes, it will Stop. You can 
watch the Master Display change as Bugbyter executes your 
Program. When Bugbyter Stops, you can verify by looking at the 
Memory Subdisplay that your program correctly loaded the five 
characters A through E into memory locations $1100 

through $1104. 


Pa] > 


5 Rito PE A Sa A 3 P NYV-8DIZC 
4894 800 196c CS 05 CS FF 33 981186811 
1F9: C1 1883; CPx #$05 P:18911999a 
LFA: F1 100A: BNE $1984 P:189119609 
tFB: 9g 1684: JSR sigag P;18119@a@06 
IFC; 01 1980; INY P;:18119869 
LFO: 81 L8BE: TYR P:18119999 
IFE: @6 1HBBF: STA $1100, P:16119600 
LFF: LO 1612: RTS P:1811960a9 
148: FF 19Q7; INX P: 88119998 
141; FF 1903; CPX #$05 P: 00119011 
182; FF 100A: BHE £1094 P:901189011 
193: FF LOC: RTS 
lod; FF 1860: INY 
195; FF 1ØDE: TYA 
1100:71 A BP POINT COUNT TRIG BROKE 
bi@rrc]°s E 1 5000 AAA 8608 o800 
tiO: GS € af 8999 899690 anaa Haag 
1193:C4 0 3 8680 8060 gaa ABA 
1184:05 —€ 4 8498 8000 agen 8808 
X 
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To modify a memory location, type an 
address followed by a colon (:), and 
then either an assembly-language 
mnemonic, a numeric constant, or a 
character string. 
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Changing Your Program in Memory 


Using Bugbyter, you can change your program in memory. This lets 
you immediately test new versions of your program without having 
to leave Bugbyter and use the Editor/Assembler to edit and 
reassemble your source program. 


For example, change the first instruction of your program, at 
address 1000, to LDY =$00. 


1. At the Bugbyter command 
level, type 
LAARA: Lo #£848 


and press (RETURN). 





Note that you must follow the address you have typed with a colon 
(:) before you type the assembly-language instruction mnemonic. 





2. To see how your entire Notice that address $1000 

program looks now, type contains the new instruction. 
18a 

and press (RETURN). 





It is also possible to change just one byte in your program. Notice 
from the Disassembly subdisplay that address $1009 (the count 
limit used in controlling the program loop) has the value $05. To 
change the number of times that your program runs through this 
loop, change this limit to $CO. 





3. At the Bugbyter command 


level, type 
Laas; CA 
and press (RETURN). 
4. To view your new program, Bugbyter displays your new 
type program in the Disassembly 
1AAAL subdisplay. 
and press (RETURN). 
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The T command places you in Bugbyter 
Trace mode and traces your program 
until it reaches the program end or a 
breakpoint. 


Z RIS PC A X ¥ S$ P_ NY-BOIZC 
9008 AG 0 188C C5 65 CS FF 33 901198011 


iFS: Cl 1968: LOY ##88 AB 2A 
1FAR: Fl 1982: LOX #349 A2 88 
1FB: 328 1984: JSR #1980 20 ƏD 18 
LEG: 6! 1987: INX ES 

1FO0: 8i 1968: CPX #$C2 E CB 
1FE: 30 188A: BNE #1604 De FS 
1FF: 37 190C: RTS 568 

190: FF 1980: INY cs 

161: FF 1Q8BE: TYR 33 

182; F LOOF: STA $1168,% 30 88 11 
103: FF 1912: RTS 68 

1084: FF 19813: BRK 20 

195: FF 1914: BRK 88 
1198:C1 A BP POINT COUNT TRIG BROKE 
11861:C2 B 1 88800 888080 AADA HOA 
LLORES G 2 8680 880800 88080 494809 
1193:C¢4¢ D 3 9860 8600 HAHA 8988 
1194:CS E 4 8860 88860 808560 40866 
& 





5. To trace this new version of Bugbyter begins tracing your 
your program, type new program starting at 
ARAT location $1000. 


me 





It takes about 30 seconds for Bugbyter to trace your whole 
program, since you made your program execute the program loop 
many more times than before. You can watch the X-register count 
how many times your program has gone through the loop. When 
Bugbyter finishes executing your program and encounters the RTS 
instruction at address $100C, it returns you to the Bugbyter 
command level. 





Viewing a Page of Memory 


The modified version of your program fills nearly a page of memory 
with the first 192 bytes of the Apple |! character set. You can view 
this area of memory using Bugbyter’s Memory Page display. 


A Tutorial: Using Bugbyter 127 





The Quit command lets you exit 
Bugbyter and return to Applesoft 
BASIC. 





128 





6. When Bugbyter completes Bugbyter replaces the Master 

tracing your program, type Display with its Memory Page 

display: a screenful of memory 

information starting at 

and press (RETURN). location $1100. Because your 
program executed the loop $CO 
(192 decimal) times, you see 
much of the Apple || character 
set displayed, including 
inverse-video and blinking 


LLee: 


characters. 


=. so +o = 


ee Oe st ee a 
Oe Oe 
ODDO YOGINHHAUSAGUGINRRK- OG 
VOODOIVDOWVODEVOVDOVIVDOWOVOIGAaO 
MWDPDDWOVOVDOVNNHAHDUWMUNF KWOK ao 
OR IDR WR WR WOR ORK OR DWR WR WR Wie 

an i 
D 
un 
w 
ui 
oO 
a 
g 
vu 
m 
ul 
vi 
gi 
© 





7. To return to the Bugbyter 


command level, press (ESCAPE). 
To exit Bugbyter and return to 
Applesoft/DOS, type 


GUT T 
and press (RETURN). 





You are now finished with this tutorial. You learned how to use 


RBCOEFGH 
I JIKLMNOP 
GRSTUVAS 
Tab sa 
BE $ EAr 
bi S A 4 
12345673 
9:;<2>?@ 
ABCDEFGH 
IJKLMNOP 
RS TUM 
kd Z E w J M 


LY ~ 
bees 


most of the features of Bugbyter. You know how 


è to use the command line; 


to read the Register subdisplay; 


to read the Stack subdisplay; 


to single-step and trace your program; 
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A memory map showing ail the 
locations in which your assembly- 
language program and Bugbyter can 
reside: see Appendix H. 


è to use the Memory subdisplay to view portions of memory; 


e to modify your program in memory and test the modified 
program; 


è to use the Memory Page display to view larger portions of 
memory. 


The remainder of this chapter describes in detail each of the 
debugging functions that you can perform using Bugbyter. The 
tutorial introduced you to many of these techniques, but the 
following sections describe these functions more completely and 
discuss some other Bugbyter features that are not mentioned in 
the tutorial. 


These sections include descriptions of 

e starting, relocating, and restarting Bugbyter 

© viewing and altering memory or 6502 registers 
è altering Bugbyter’s Master Display layout 


e debugging techniques for controlling the execution of your 
program, including: single-step mode; trace mode and 
transparent breakpoints; execution mode and real breakpoints 


è debugging real-time code 


e debugging programs that use the keyboard and video display. 


Using Bugbyter 


Bugbyter is a 6.7K ($1A00 byte) binary program that must be fully 
resident in memory whenever you use Bugbyter to test or debug 
your programs. Since your own program must share the Apple II's 
memory with Bugbyter, you must be careful that the two programs 
do not overlap each other in memory. 


You load and execute Bugbyter using the DOS BRUN command, 
just as you did in the preceding tutorial; that is, from either 
Appiesoft or Integer BASIC, type 


BRUM BUGEY TER 


and press to run the Bugbyter program. Your Apple |! 
reads the Bugbyter program from your disk and loads it into 
memory from location $7C00 to $95FF. This default Starting 
address ($7C00) locates Bugbyter just below DOS Buffer One, 
high enough in memory not to interfere with most small-to- 
medium-sized assembly-language programs. 
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Uniess you specify a starting address 
with the BRUN command, the Bugbyter 
program loads starting at memory 
address $7C00. 
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Relocating the Bugbyter Program 


lf your own program uses memory locations that fail within the 
block from $7C00 to $95FF, you must relocate Bugbyter to some 
other memory location. You can specify any starting address 
from $800 to $7C00 when you type the BRUN command to 
execute Bugbyter. For example, to run Bugbyter starting at 
location $1000, type 


BRUM BUCY TER, AF1 00G 


and press (RETURN). Your Apple || loads Bugbyter and executes it 
from locations $1000 through $29FF. 





Using Bugbyter in a Language Card 
To use Bugbyter in a Language Card or a RAM card, type 
BRUM GUGLOADER 


and press (RETURN). The Bugioader program automatically loads 
and executes Bugbyter in your Language Card or RAM card 
Starting at location $D000. 


When Bugbyter is running in a Language Card, the Language Card 
must not be write-protected. Bugbyter must be able to store 
temporary variables within this memory block. 


You can also run the Bugbyter from some other location in the 
Language Card; you do not have to run it at the starting address 
fixed in the Bugioader. The Bugloader program performs the same 
function as if you type from either BASIC: 


i ee: 
TA31 LA31 PSsee<Psee, PPM Cass Cass 
BRUM BUCEY TER, At0ae8e 

These three lines 

1. call the Apple II Monitor; 

2. copy the Monitor from ROM into the Language Card; 


3. load and execute Bugbyter at the first location in the Language 
Card. 
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To execute Bugbyter at another location within the Language 
Card, you can retype these three lines yourself and BRUN 
Bugbyter at any address from $D000 to $DE00. 


The Bugbyter program is self-modifying; that is, once you BRUN the 
program at a certain address, Bugbyter modifies itself so it can 
execute at that address. For this reason, if you want to move Bugbyter 
around in memory you should BLOAD Bugbyter before moving it, 
rather than using BRUN. 


For example, if the program you are debugging does not require DOS, 
you might want to run Bugbyter at address $A600 to leave more room 
for your own program. To do this, BLOAD Bugbyter at some lower 
address ($7C00, for example), and then use the Monitor to move 
Bugbyter to start at address $A600. 





Entering the Monitor 
From the Bugbyter command level, you can enter the Apple || 
Monitor to use the Monitor’s block memory moves and other 
capabilities not provided by Bugbyter. Your Apple lI Reference 
Manual describes the features of the Apple || Monitor. 
To enter the Monitor, type 

t1 
and press (RETUAN). After you finish using the Monitor, type 
and press to return to the Bugbyter command level. 





Restarting Bugbyter 


If you shouid ever exit Bugbyter for any reason, either into the 
Monitor or into BASIC, you can use the Monitor’s (CONTROL)-(Y) 
vector to restart Bugbyter, or you can use Bugbyter’s load 
address. 
For example, if you run Bugbyter by typing 

ERUH BUGE TER, AFSEeH 


and press (RETURN), you can restart Bugbyter from either Applesoft 
or Integer BASIC by pressing and typing either 


CALL 1516 This uses the Monitor’s (CONTROL)-(Y ) vector. 
or 
CALL 8132 This uses Bugbyter’s specific load address. 


and pressing (RETURN). 
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From the Monitor, you can reenter Bugbyter by pressing 
(CONTROL)-(Y ) 


and then (RETURN). 


MMe Memory and the Bugbyter Displays 


In the Bugbyter tutorial, you were introduced to many of 
Bugbyter’s features for viewing and altering the contents of 
memory locations and registers. The following section describes in 
more detail how you can do this and also describes how you can 
alter the layout of Bugbyter’s Master Display. 


Using Bugbyter, you can view the contents of memory in several 
different ways. 


e You can use the Stack and Disassembly subdisplays of the 
Master Display to show the contents of specific regions of 
memory. Select the region that shows the Disassembly 
subdisplay by using the Load (L) command described in the 
tutorial. 


èe You can use the Memory subdisplay of the Master Display to 
show the contents of several individual memory locations. Use 
the MEM command to set particular memory addresses for 
each cell of this subdisplay. 


è You can use the Memory Page display to show the contents of 
184 ($B8) contiguous memory locations both as hexadecimal 
values and as Apple || characters. 


eae 


Using the Memory Subdisplay 


The Memory Cell subdisplay of Master Display continuously 
displays the contents of several individual memory locations that 
you can select. You can use the MEM command to set the memory 
addresses in one or more cells of this display. If you want, you can 
first use the Set command to increase the number of ceils in this 
subdisplay. 
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The MEM command lets you modify 
Bugbyter’s Memory subdisplay. 


Unless you specify otherwise, Bugbyter 
displays the contents of each memory 
ceil in hexadecimal notation and as a 
character. 


Press and then to 


display the next memory page. 





To set addresses in the Memory subdisplay from the Bugbyter 
command level, type 


MEM 


and press (RETURN). The cursor moves to the first address at the 
top of the Memory Subdisplay. You can now choose 


è to type a smaller than four-digit hexadecimal address for this 
memory cell, and press (RETURN); 


e totypea four-digit address; the cursor automatically moves to 
the next address; 


* to use (=), ©, or to move the blinking cursor to 


another memory cell. 


Before typing an address into a memory cell, you can select 
whether Bugbyter will display the contents of that memory location 
as both a hexadecimal value and an Apple || character, or as a 
four-digit hexadecimal address. Before typing the address into a 
memory cell, type 


H 


to display the contents of the location in hexadecimal and asa 
character, or 


F 
to display the contents of the two consecutive locations 


(address + 1 and address) as a four-digit hexadecimal address 
pointer (most significant byte first). 


To return to the Bugbyter command level, press (ESCAPE). 


Viewing the Memory Page Display 


To view an entire screenfull of memory locations (two-thirds of a 
6502 memory page) from the Bugbyter command level, type the 
starting address of the memory block, type a colon (:), and press 
(RETURN). For example, if you just completed the tutorial and have 
the Apple II character set in memory at address $1100, type 


114g 


and press to tell Bugbyter to replace the Master Display 
with the Memory Page display having the address 1100 in the 


upper-left corner. 


— 
— 
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Your display might show different 
values, depending on the current 
contents of this region of memory. 


The memory assignment command: see 
the section "Altering the Contents of 
Memory.” 
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1180; 81 @2 83 84 85 06 BF 838 ABCDEFGH 
1188: 89 BA ØB BC BO BE ØF 1ð ITJKLMNOP 
LiL ae 13 14 13 16 17 18 | GRSTUVUX 
fiis: 19 1Ñ £8 1C {0 1E iF 20 Yet. 
1120: Ep22 23 24 29 26 27 26 !"RS4R < 
1126: 29 2A 28 2G 2D 2E èf SG ?ž*,-,.70 
1128; singe 33 34 39 36 37 39 123456798 
1138; 39 3A 3B 3C 30 SE SF 40 9: : <2>78 
1140: 41 42 43 44 45 46 47 43 ABCDEFGH 
1148: 49 4A 48 4C 40 4E 4F 50 I[JKLMNO 
1150: $1 $2 53 54 55 36 37 58 QRSTUVWX 
1199: S39 SA SB SC 30 SE SF 60 YazCN I 
1168: 61 62 63 564 65 56 67 563 |!"#S4%R < 
1163: 69 6A 6B 6C 6D SE 6F 70 >+, -,70 
Linon E oS 73 74 75 76 Pe TI 12345673 
1178: 79 7A 7B 7C 70 TE 7F 90 9:;<2>78 
1134: 31 82 33 34 35 36 37 33 ABCDEFGH 
11383: 89 3A 3B 3C 30 3E 3F 38 IJKLMNOP 
1199: 91 92 33 34 35 96 97 98 QARSTUVWK 
1198: 999A 98 JC 90 JE OF AD YeC.4 
LIRO: Al AZ AS AF AS AG AP AS | "HSAR < 
L1AS: AS AR AB AC AD AE AF BH 3K+,-.78 
+ al Bi B2 83 B84 65 B6 87 BS 12345573 


Bugbyter displays the contents of memory in a table with eight 
memory locations to a line. The contents of each memory location 
are shown first in hexadecimal and then as the equivalent Apple |I 
character. Each line of this table starts with the memory address of 
the first byte shown on that line. The normal Apple || character 
set is: 


00-3F inverse-video characters 

40-7F flashing-video characters 

80-FF normal-video characters (two sets of alphabetic 
characters) 


Bugbyter displays the colon prompt on the last line of this display 
and will accept either another address followed by a colon to 
display another memory page, or a memory assignment 
command. 


To return to the Bugbyter command level and the Master Display, 
press (ESCAPE). 
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Altering the Contents of Memory 


Using Bugbyter you can change the contents of any RAM memory 
location in your Apple Il. From the Bugbyter command level or 
from the Memory Page display, you can change one or a sequence 
of memory locations by typing a hexadecimal address followed by 
a colon and 


@ one or more hexadecimal bytes 


è one or more character strings (enclosed in double or single 
quotes) 


èe combinations of the two above 


@ 6502 instruction mnemonics and operands. 


You can freely mix hexadecimal numbers and character strings of 
any length in your memory assignment commands, separating 
each item with one or more spaces. 


When you are entering character strings, Bugbyter stores the 

‘characters with their most significant bit on if you enclose the 
characters in double quotes (’’). Bugbyter stores these characters 
with their most significant bit off if you enclose the character string 
in single quotes. 


For example, if you type 
SHS “HELLO” SO 


and press (RETURN), Bugbyter fills the memory locations from $805 
to $80A with the bytes $C8, $C5, $CC, $CC, $C5 (“HELLO”), 
followed by a byte with the value of $8D. Since you used double 
quotes to delimit the character string, the character codes are 
stored with their most significant bit on. 


Bugbyter also accepts 6502 instruction mnemonics in a memory 
assignment command. You must use the standard address mode 
syntax when specifying operands, and you must type each 
assembly-language instruction in a separate memory assignment 
command. For example, if you type 


Laga: LOY #F20 


and press (RETURN), Bugbyter assembles this statement and stores 
the two resulting bytes ($A0 and $80) in the memory locations 
$1000 and $1001. 
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Any time you alter a memory location that is currently displayed on 
either the Master Display or the Memory Page display, 

Bugbyter immediately updates the display to show 

any changes. 





Altering the Contents of Registers 


The Bugbyter Master Display always shows the current contents of 
the 6502 registers as they appear to the program you are 
debugging. You can change the contents of these registers at any 
time from the Bugbyter command level. 


To change the contents of a 6502 register from the Bugbyter 
command level, type the name of the register followed by an equal 
sign (=), the vaiue to be stored in the register, and press (RETUAN). 
For example, if you type 


A= 20 


and press (RETURN), Bugbyter sets the contents of the A-register 
to $8D. This value is immediately reflected under the A-register 
labej in the Register subdisplay. In the same manner, you can 
change the C, R, PC, A, X, Y, S, and P registers to any value you 
wish. The Bugbyter’s 8 flag is not a register, and you cannot 
change this flag using this register-assignment command. The NV- 
BDIZC display is the binary representation of the P-register. To 
change individual bits in the P-register, type F = followed by the 
appropriate hexadecimal number. 





Warning 

Bugbyter uses the first 32 bytes of the 6502's stack (locations $100 to 
$11F), and any attempt by you or your program to alter the stack pointer 
to point into this region may result in a collision between Bugbyter and the 
program you are debugging. 


Bugbyter flashes a warning in the Stack subdisplay area if you or your 
program sets the stack pointer to any value less than $20 (Since the stack 
pointer points only to locations in page one of memory, a stack pointer 
value of $20 implies a memory address of $120). 
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By the Way: To help you when you are assigning numeric values to 
memory locations or registers, or whenever you are converting 
numbers from one base to another, the Bugbyter performs simple 
conversions from hexadecimal to decimal, or from decimal to 
hexadecimal. For example, from the Bugbyter command level, if you 


type 
CJs 


and press (RETURN), Bugbyter converts the hexadecimal number $C3 
to its decimal equivalent and display this value following the equal Sign: 


FC 3=00195 


IN an equivalent manner, you can type hexadecimal numbers without 
the dollar sign ($). For example, if you type 


= 
4 
aa! 


c2 


and press (RETURN), Bugbyter treats this command the same way it did 
the $C3= command above. 


To convert a decimal number to its hexadecimal equivalent, you must 
precede the decimal number with a plus (+) or minus (-) sign to 
distinguish it from a hexadecimal number. For example, if you type 


+43= 


and press (RETURN), Bugbyter responds by displaying the hexadecimal 
equivalent following the equal sign on the command line: 


+43=F26 


Altering Bugb yter’s Master Display Layout 


Bugbyter’s Master Display has several Subdisplays that let you 
view many different items of information at once. You can 
customize Bugbyter’s Master Display layout to alter the relative 
sizes of some of these Subdisplays, allowing you 


e to set more or fewer program breakpoints—the Breakpoint 
subdisplay; 


e to view larger or smailer Portions of your disassembled 
Program—the Code Disassembly Subdisplay; 


© to view larger or smaller regions of the memory stack —the 
Stack subdisplay; 


© to view more or fewer memory cells—the Memory subdisplay. 
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The SET command lets you set the 
relative sizes of the various Bugbyter 
subdisplays. 
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To change the relative sizes of these subdisplays, you use the Set 
command. From the Bugbyter command level, type 


SET 


and press (RETURN). Bugbyter displays a sketch of the Code 
Disassembly and the Breakpoint subdisplays and allows you to set 
the relative sizes of these displays. 


Now you can 


® use (—) to increase the number of breakpoints that are 
displayed and simultaneously decrease the size of the Code 
Disassembly subdisplay; 


è use (—) to decrease the number of breakpoints that are 
displayed and simultaneously increase the size of the Code 
Disassembly subdisplay. 


When you are satisfied with the relative sizes of these subdispiays, 
press to fix the relative sizes as you have selected them. 


You can now select where Bugbyter displays the “next instruction 
to be’executed”’ bar in the Code Disassembly subdisplay. Use the 
(—) and (—) to adjust the position of the inverse-video bar within 
the Code Disassembly display. The position of this bar divides the 
subdisplay into the instructions that have been executed (above - 
the bar) and instructions not yet executed (at and below the bar) 
when you are tracing or single-stepping your program. Press 
when you are satisfied with the bar position. 


Bugbyter then displays a sketch of the Stack and Memory Cell 
subdisplays. Use the (—) and (>) to adjust the relative sizes of the 
Stack and Memory subdisplays, just as you did for the 
Disassembly and Breakpoint subdisplays. 


When you are satisfied with the relative sizes of these displays, 
press to fix the sizes. Then use the (—) and (=>) to adjust 
the position of the stack-pointer bar within the Stack subdisplay. 
Typically, you want this bar near the top of the subdisplay, since 
information on the stack appears below this inverse-video bar. 


When you are done, press to return to the Bugbyter 
command level. 
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When you use the Set command, you do not change the contents 
of the Memory subdisplay or the Breakpoint subdisplay. You can 
recover any Memory cells or breakpoints that are no longer 
displayed by using the Set command to enlarge these subdisplays 
and to display this information once again. 


Controlling the Execution of Your Program 


There are probably as many ways to debug a program as there are 
ways to write a program; both are related to a programmer's 
particular style. This manual is not intended to teach you a 
particular way to debug your programs any more than it is 
intended to teach you programming style. There are, however, 
several techniques for controlling the execution of your program 
that are very useful for debugging. This section discusses some 
debugging techniques that you can use with Bugbyter; they include 


è single-stepping your program 
è tracing your program 


e executing your program directly on the 6502. 





Using the Single-Step and Trace Modes 


Bugbyter’s Single-Step and Trace modes provide you with a 
powerful debugging environment. Bugbyter is capable of tracing 
almost any executable 6502 program, inciuding interrupt and 
timing-sensitive code. You have already found the Single-Step and 
Trace modes easy to use if you followed the Bugbyter tutorial. 


When you enter Single-Step or Trace mode, Bugbyter removes the 
command prompt from the command line and replaces it with the 
words SIHGLE 2TEF or TRACE. Once you enter one of these 
modes, you can no longer type commands at the Bugbyter 
command level. Instead, you can type a set of single-keystroke 
commands that give you access to a variety of debugging features. 
To return to the Bugbyter command level, simply press (ESCAPE). 


Table 4-2 shows the functions that you can perform and the single 
keystrokes that you use. 
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Tabie 4-2. Trace and Singie-Step 
Keystroke Commands 
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Trace or 

Single-Step Operation 

Return to Bugbyter command level ESCAPE 
Single step (execute) one instruction SPACE 


Skip next instruction 

Trace program until a breakpoint or end instruction 
Trace until an RTS 

Clear Cycie Count register 

Use hand control 0 to adjust Trace Rate 


Use Keyboard Rate to adjust Trace Rate; (set R=vaiue 
before entering Trace mode) 


Turn off Bugbyter Sound (Quiet) 

Turn on Bugbyter Sound 

Display primary screen 

Dispiay secondary screen 

Display Text screen 

Display Low-resolution graphics screen 
Dispiay High-resolution graphics screen 


Display Fuil screen graphics 


000000 oe aii 


Display Mixed graphics screen, with Bugbyter command 
line visible 





To access any of these debugging functions, you need type only 
the singile keystroke. To return to the Bugbyter command level and 


view the Master Display, press (ESCAPE). 


You can reenter Single-Step mode from the Bugbyter command 
levei to continue single-stepping by typing 


and pressing (RETUAN), or you can enter Trace mode by typing 


- 


and pressing (RETUAN). Bugbyter remembers the last instruction it 
executed before leaving Trace or Single-Step mode, and continues 
from the next instruction whenever you reenter Trace or Single- 
Step mode without specifying a starting address. 
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Single-Stepping Your Program 


When you debug a program, you spend much of your time 
observing the execution of your program and verifying that it 
works correctly. The single-step function of the Bugbyter was 
introduced in the Bugbyter tutorial. In Single-Step mode, Bugbyter 
allows your Apple || to execute a single instruction at a time, 
stopping after each instruction to allow you to observe the result. 


To enter Single-Step mode from the Bugbyter command level, 
type the memory address of the first instruction that you wish to 
execute, followed by an (S), and press (RETURN). In the example in 
the tutorial, you typed 


LARAS 


After you type the single-step command, Bugbyter shows in the 
Disassembly subdisplay the first instruction to be executed. To 
execute this instruction, press (SPACE). Bugbyter executes this 
single instruction and updates the screen to show you any effects 
that occurred due to the execution of the instruction. 


To continue executing succeeding instructions, press for 
each instruction to be executed. After Bugbyter executes each 
instruction, it updates its Master Display, allowing you to verify that 
your program has executed correctly, or showing you exactiy 
where your program went awry. 


Using Trace Mode 


You will find Bugbyter’s Single-Step mode very useful for 
observing short programs or small portions of larger programs. 
For completely testing programs that are medium to jarge in size, 
however, single-stepping through each instruction is rather slow 
and tedious. 


To test portions of medium to large programs, you will find it more 
efficient to let Bugbyter execute whole portions of your program at 
a time, interrupting this execution at places you specify to allow 
you to observe program results and the status of registers and the 
stack. This technique lets you skip over portions of your program 
that are operating correctly and allows you to get swiftly to the 
location of a problem. 
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The R command allows you to trace 
your program up to the occurrence of 
the next ATS instruction. This provides 
an easy way to debug individual 
subroutines within your program. 


A transparent breakpoint does not 
alter your program's code in any way. A 
reai breakpoint, used in Execution 
mode, actually alters your program 
temporarily. 
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Tracing Subroutines 


Most good programs are written using subroutines as a basic 
building block. Rather than single-step your program one 
instruction at a time, Bugbyter allows you to use Trace mode to 
step easily through your program one subroutine at a time. 


You can activate this feature only from Bugbyter’s Single-Step 
mode. To trace your program until the next occurrence of an RTS 
instruction, that is. until the end of the next subroutine, type 


F 


while you are in Single-Step mode. Bugbyter begins executing 
each instruction of your program in sequence, updating the Master 
Display after each instruction, until it encounters an RTS 
instruction in your program or a breakpoint. When Bugbyter 
encounters an RTS instruction, it returns you to Single-Step mode 
and lets you observe the results of the subroutine and continue 
debugging as you wish. 


Setting Transparent Breakpoints 


A common way to control Bugbyter’s trace of your program is to 
set breakpoints at particular locations within your program. 


When you are debugging in Trace or Single-Step mode, Bugbyter 
monitors your Apple Il’s program counter (PC) before executing 
each instruction and compares it to any breakpoints that you may 
have set in the Breakpoint subdisplay. If your program reaches one 
of these breakpoints (that is, if the 6502's program counter 
matches the address of a breakpoint), Bugbyter interrupts your 
program and returns you to Bugbyter’s command level. 


lf you do not set any breakpoints, or if Bugbyter does not 
encounter any while executing your program, Bugbyter continues 
executing your program until you press (ESCAPE), or until it 
reaches the end of your program. 


To set transparent breakpoints, you should be familiar with the 


breakpoint subdisplay area (Figure 4-8) of Bugbyter’s Master 
Display. 
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Figure 4-8. The Breakpoint Subdisplay 


To set a breakpoint address, type EF 
followed by a breakpoint number. 
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2 COMPUTER-AOVANTED 


The Breakpoint subdisplay is in the lower-right section of 
Bugbyter’s Master Display. You can use the Set command to 
increase or decrease the number of breakpoints that are 
displayed. The Breakpoint subdisplay has four column headings, 
where each line under these four headings represents one 
breakpoint. For each breakpoint 


@ POINT is the hexadecimal address of the breakpoint. 


e COUNT is the number of times that Bugbyter has encountered 
this breakpoint address while executing your program since the 
Bugbyter last Triggered at this breakpoint. 


e TRIG is acount that you can specify. Bugbyter does not 
interrupt program execution until it encounters this particular 
breakpoint the number of times that you specify. A TRIG count 
of 1 causes Bugbyter to interrupt program execution the first 
time it encounters this breakpoint. 


èe BROKE is the number of times Bugbyter has actually Triggered, 
or interrupted program execution, at this particular breakpoint. 


To enter a breakpoint address from the Bugbyter command level, 
type EF followed by a breakpoint number. For example, to set a 
breakpoint to be displayed in row number 1 of the Breakpoint 
subdisplay, type 


EF 1 
and press (RETURN). 
When you type this breakpoint setup command, Bugbyter moves 
the cursor to the first zero in the POINT field of the breakpoint row 
you specify. Enter a hexadecimal address in this field to represent 


the address of breakpoint +1. Use (—) to move the cursor to the 
TRIG field on that same breakpoint line. In the TRIG field, type a 
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The CLR command allows you to clear 
one or all transparent breakpoints. 


Ta 


hexadecimal number greater than zero. If you want Bugbyter to 
stop on the first occurrence of this breakpoint, type 1 in this field. 
lf you leave TRIG set to 0, Bugbyter ignores this breakpoint. Press 
when you finish setting the breakpoint address and the 
TRIG count. 


You typically might set breakpoints at critical locations in your 
program, such as just after a call to an important subroutine. 
When you are tracing your program, you can then verify that the 
results from this subroutine are correct and are stored in the 
proper registers or memory locations. Other locations to test 
might be after an important compare instruction, or at any place 
you want to check the status of your program. 


Using Breakpoints 


Once you set breakpoints where you want them, you can use Trace 
or Single-Step mode to monitor the execution of your program. 
Every time Bugbyter encounters an instruction located at a 
breakpoint address (Point), Bugbyter increments the Count for 
that breakpoint and compares this Count to the Trig value you set 
for that breakpoint. When the Count equals your Trig value, 
Bugbyter stops your program execution before executing the 
instruction at the Point address. Bugbyter then highlights the row 
in the Breakpoint subdisplay corresponding to the breakpoint that 
triggered and clears the Count. 


You can then observe all the 6502 registers, stack, and other 
conditions that existed just before your program was interrupted 
by the occurrence of the breakpoint. If you want to continue 
executing your program from the point where the breakpoint 
occurred, type 


~ 
and press to reenter Trace Mode, or type 


and press to enter Singie-Step mode. 


Clearing Transparent Breakpoints 
To clear a particular breakpoint, type CLF followed by the 
breakpoint number, and press (RETURN). 
To clear all breakpoints, type 
CLR 
and press (RETUAN). 


The Bugbyter Debugger 








The Bugbyter dispiay options are shown 
at the right edge of the Code 
Disassembly subdisplay, just to the 
right of each associated instruction. 


Adjusting the Trace Rate 


During tracing, Bugbyter interprets each 6502 instruction of your 
program. This means that the 6502 microprocessor is executing 
the Bugbyter program, which in turn is executing your program 
code. The result of this process is that the code you are tracing 
using Bugbyter executes much slower than if it were executed 
directly by the 6502 microprocessor. You can adjust the rate at 
which Bugbyter traces your code by one of several methods. 


è Before you enter Trace mode, set a value in Bugbyter’s Trace 
Rate register, displayed in the Register subdisplay. Type F=, 
followed by a hexadecimal value from 0 to FF, where 0 is the 
fastest rate and FF is the slowest. Press (RETURN). When you 
enter Trace mode, Bugbyter uses this rate setting to control the 
speed of its trace. 


è |f you have hand controls for your Apple Il, use them to adjust 
the trace rate while you are in Trace mode. While in Trace mode, 
press (P) and use hand control 0 to adjust the trace rate. To 
return to the keyboard (R-register) rate, press (K) to disable 
the hand control. 


è Before you enter Trace mode, type IFF from the Bugbyter 
command level and press (RETURN). This clears Bugbyter’s 
Master Display. Turning off the Master Display greatly increases 
the speed of tracing once you enter Trace mode. To restore the 
Master Display, type OH and press from the Bugbyter 
command level, or press (ESCAPE), type IH, and then press 
from Trace mode. 


Using Display Options in Trace and Single-Step Mode 


You can select one of seven display options for Bugbyter to use 
during Trace and Single-Step mode to display different types of 
relevant information. 


To select one of these options, you must do so from the Bugbyter 
command level before you enter Trace or Single-Step mode. 
Table 4-3 shows the display options that you can select and the 
commands you can use to select a particular option. You can 
select only one option at a time; Bugbyter displays only the most 
recently selected option. 
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Table 4-3. Code Disassembly Display 
Options 
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Display Option To Select, type 


command and press (RETURN): 
A-register in binary =A 
X-register in binary = 
Y-register in binary gsr 


Stack Pointer in binary j=: 


Processor Status Byte in binary J=F 
Machine-instruction bytes in hex Q=6 
Computed effective addresses, relative J=E 


branches, and instruction cycies 


The last option shown in Table 4-3, the O=E display option, 
requires some extra discussion. There are four 6502 addressing 
modes for which the 6502 internally computes an effective 
address. These modes are: 





Mode Example 
indexed LDA #788, % 
indirect JMP ¢ $308» 
indexed indirect LOR (£18, «3 
indirect indexed LOA ($10), Y 





During Trace or Singie-Step mode, Bugbyter computes the actual 
or effective address for each instruction using the current contents 
of registers or memory ceils at the time the instruction is executed. 
lf you select the O=E option, Bugbyter displays these effective 
addresses in the Disassembly subdisplay. Bugbyter also displays 
all relative branch offsets (the hex byte operand of a branch 
opcode) when you select this option. 


When you select the O=E option, Bugbyter displays the number of 
instruction cycles used by each instruction. This count of the 
number of cycles appears in parentheses to the right of the 
Disassembly line for each instruction that is executed. 
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As an example of this display option, if you type a command 
followed by (RETURN), the command 
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clears the Cycle Count register in the Register subdisplay 


sets the Display Option to E 


sets the accumulator to $12 


activates Single-Step mode at the start of the Monitor WAIT 
routine 


starts Bugbyter tracing until an RTS instruction is 


encountered 


Bugbyter begins tracing the Monitor WAIT routine; the command 
line at the bottom of the Master Display shows 


TRACE AWAITING RTS 


The rest of the Master Display changes rapidly. You can watch the 
Cycle Count register shown in the upper-left corner of the Master 
Display incrementing after each instruction is executed. After a 

few seconds, the Master Display halts and shows 
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The IN command causes Bugbyter to 
insert 6502 SRK opcodes at all 
breakpoint addresses shown in the 
Breakpoint subdisplay. 
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The Cycle Count register in the upper left-corner shows $41E 
(1054 decimal) processor cycles, representing the time required to 
execute the WAIT routine when the accumulator is preset to $12. 
Using a cycle time of one microsecond, this cycle count represents 
a WAIT of approximately one millisecond (0.001 seconds). 


Bugbyter increments the Cycie Count register only when you select 
the O=E display option before entering Trace or Singie-Step 
mode. The Cycle Count register is also not incremented if you turn 
off the Bugbyter Master Display using the Off command. 





Using Execution Mode 


There may be times when you want to execute portions of your 
program at the full speed of the 6502 microprocessor, without 
having Bugbyter continuously check for breakpoints and so slow 
down your program's execution. You can do just this by using 
Bugbyter’s Execution mode. 


In Execution mode Bugbyter executes your program directly, at 
the full speed of the 6502 microprocessor. To debug your program 
in Execution mode, you must use real breakpoints, rather than 
transparent breakpoints, to controi your program's execution. 


A real breakpoint is a 6502 Break opcode ($00) that Bugbyter 
places at the breakpoint address in your program code. Real 
breakpoints differ from transparent breakpoints in that Bugbyter 
must aiter your program code when it inserts real breakpoints; 
transparent breakpoints do not change your program code in any 
way. 


Setting Real Breakpoints 


To set real breakpoints at the addresses shown in the Point 
column of the Breakpoint subdisplay, type 


IH 


from the Bugbyter command level, and press (RETURN). This 
command causes Bugbyter to insert 6502 BRK opcodes (00) at all 
the breakpoint addresses (all Point addresses with their 
associated Trig’s set to greater than zero). Bugbyter displays an I 
for breakpoints IN under the B-flag in the register subdisplay at 
the top of the screen. 


Once you insert real breakpoints in your program code, you can 


debug your program while executing it at the full speed of the 6502 
microprocessor. 
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The OUT command causes Bugbyter to 
remove ail the real breakpoints inserted 
by a previous In command. 
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When real breakpoints are in your program, Bugbyter does not allow 
you to add, change, or clear any breakpoints. To modify any of the 
breakpoint information, you must first instruct Bugbyter to take real 
breakpoints out. Only after you do this will Bugbyter allow you to 
modify your breakpoints. 


To take the real breakpoints out of your program code, type 
CLIT 


from the Bugbyter command level and press (RETURN). This 
command foices Bugbyter to remove the break opcodes that it 
inserted when you last used the In command, and restores the 
6502 instruction opcodes originally stored there. The B-flag that 
monitors the status of real breakpoints in the Register subdisplay 
at the top of the screen displays the letter 1 for breakpoints Out. 





A Warning 


The G command causes Bugbyter to 
enter execution mode and begin 
executing your program directly. 


Once you set real breakpoints in your program, Bugbyter alters your 
program by inserting break opcodes at every breakpoint address. If you 
exit Bugbyter before you remove the real breakpoints, your code may be 


riddied with unwanted 6502 breaks. Be sure to type 


IT 
and press (RETURN) to return your code to its original condition. 





If you enter Trace mode when real breakpoints are in, Bugbyter 
operates just as it does when real breakpoints are out. You wiil find 
it more convenient to use transparent breakpoints if you wish to 
debug your program in Trace or Single-Step mode; real 
breakpoints are only necessary when you are debugging your 
program in Execution mode. 


Debugging Your Program in Execution Mode 


To execute your program directly from the Bugbyter command 
level, type a starting address foilowed by '> (for GO) and press 
(RETURN), or simply type 5 and press (RETURN). 


When you type this command, Bugbyter enters Execution Mode 
and starts executing your program from the starting address that 
you indicated. If you didn’t type a starting address, Bugbyter uses 
the last starting address that you specified with either the Single- 
Step, Trace, or Go commands. For example, to execute your 
program starting at location $1000, type 


AAAG 
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The J command allows you to resume 
execution of your program after 
execution was haited by a breakpoint. 


150 


and press (RETURN). Bugbyter treats this command similarly to the 
Monitor G command: Bugbyter pushes a return address onto the 
stack before executing your program code. If your program 
encounters a return-from-subroutine (RTS) instruction, you return 
to the Bugbyter command level. The same result occurs if your 
program encounters a BRK opcode or a breakpoint. 


To continue executing your program after a breakpoint has forced 
Bugbyter out of Execution mode, type 


and press (RETURN). This command does not push a return address 
onto the stack, assuming that you have already set up Execution 
mode using the G command. When first executing your code, type 


{star ting-addresseG 
and press (RETURN). After encountering any break opcodes, type 
ul 


and press (RETURN) to continue direct real-time execution. 


Note: Because the J command does not push a return address onto 
the stack, you shouid aiways begin debugging in Execution Mode using 
the G command. If you start Execution mode with the J command and 
your program encounters an RTS instruction, the 6502 uses an 
undefined address from the stack with unpredictable results. 


When the 6502 encounters a BRK opcode, that is, either a 
breakpoint inserted by Bugbyter or part of your program code 
itself, the 6502 passes control back to the Bugbyter program. If the 
BRK opcode was a breakpoint inserted by Bugbyter, the 
breakpoint is shown in inverse-video in the Breakpoint subdisplay, 
and you return to the Bugbyter command level. If the BRK opcode 
was not a breakpoint inserted by Bugbyter, control passes to the 
Monitor. 





Debugging Real-Time Code 


lf you are debugging a program that contains real-time sensitive 
code or cails real-time Appie II DOS routines, these portions of 
your program will not function correctly if you try to trace their 
execution in Bugbyter Trace or Single-Step mode. 
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A soft switch is a memory location near 
the beginning of the Bugbyter program 
that allows you to control some of 
Bugbyter’s features, A complete list of 
the Bugbyter soft switches: see 
Appendix A. 


Table 4-4. Bugbyter Real-Time Soft 
Switches 





There are two ways that you can debug this type of program using 
Bugbyter, one of which has been described in the section “Using 
Execution Mode.” The other alternative is to use the more 
powerful debugging capabilities of Bugbyter’s Trace or Single- 
Step modes to debug the timing-insensitive portions of your 
program, while still executing the real-time routines of your 
program at the full speed of the 6502 microprocessor. 


Prime examples of real-time sensitive code are the core routines 
associated with the Apple || DOS operating system. The read-data, 
write-data, read-address and track-seek routines are very 
sensitive to cycle speed variation. These core routines will not 
function at all if you trace them using Trace or Single-Step mode. 
To execute these subroutines from a program that you are tracing 
using Bugbyter, you must use Execution mode. 


Bugbyter allows you to execute subroutines in Execution mode 
while tracing your calling routines in Trace or Single-Step mode. 
You can set up this method of operation by designating a region of 
memory containing the real-time routines that Bugbyter always 


‘executes in Execution mode. You do this by setting two soft- 


switch addresses within Bugbyter. 


Offset from the beginning of the Bugbyter program, at locations 
start+$0A and start+$0B, are the two bytes that you can set to 
define the starting address of this real-time region. At locations 
start+$0C and start+$0D are two bytes that indicate the ending 
address of this region. Table 4-4 lists these real-time soft switches. 





Soft-Switch Byte Relative Address Absolute Address 
High-byte of region start address start + $0A 7COA 
Low-byte of region start address start + $08 7C08 
High-byte of region ending address start + $0C 7C0C 
Low-byte of region ending address start + $00 7C00 





When you are tracing your program in Trace or Single-Step mode, 
any subroutine (JSR) calls to locations inside this defined region 
cause Bugbyter to transfer control of your program from Trace or 
Single-Step mode to Execution mode. This means that the 
subroutines in this region execute at the full speed of the 6502 
microprocessor. When the 6502 encounters the return from 
subroutine (RTS) instruction that transfers control back to your 
calling routine, Bugbyter reactivates Trace or Single-Step mode 
and continues executing your main or calling program. 
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For example, if you have a 48K version of DOS in memory, with 
Bugbyter loaded at $7CO0, type 


TCRA: ABS PP PE 


and press to designate a real-time region extending from 
location $8800 to $FFFF; this includes the DOS core routines, 
RWTS, peripheral I/O, BASIC, and the Monitor). If you then type 


248; JSR ASEE 
which is the starting address of the DOS Catalog routine, and type 
383; ERE 
you set up a calling program for the DOS Catalog routine. Then 
type 
CFF 
to turn the Master Display off, and type 
SAAT 


to trace your calling program. 

This command sequence causes Bugbyter to begin tracing DOS's 
Catalog routine until it encounters a JSR to the Read-Write-Track- 
Sector (RWTS) routine at $BD00— inside your real-time region 
($8800-FFFF). At this time, Bugbyter enters Execution mode and 
allows RWTS to execute directly under the 6502 microprocessor— 
seeking tracks and reading sectors from the disk in real-time. 
When the RWTS routine exits to DOS (RTS), Bugbvier reenters 
Trace mode and continues tracing the code that follows the call to 
RWTS (JSR AS6E). 





Debugging Programs that Use the 
Keyboard and Dispiay 


Bugbyter is a screen-based debugger and so requires the use of 
the screen in order to relay information to you. Likewise, many of 
Bugbyter’s features require you to type commands at the 
keyboard while you are debugging. To debug your own programs 
that use the keyboard and screen, you must take care to eliminate 
contention between Bugbyter and your own program for the use of 
the keyboard and display. 
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The Off command clears the first 

23 lines of the text page, allowing your 
program to use your video screen 
without interference from Bugbyter. 


The On command returns Bugbyter to 
its normal full-screen display mode 
following a previous Off command. » 


A soft switch controis Bugbyter’s 
polling of the keyboard, allowing you to 
debug programs that require extensive 
keyboard input. 





Eliminating Screen Contention 


Since Bugbyter displays all information on the screen using 
absolute screen addressing, any programmed output by your 
program using the Apple II’s I/O hooks (CSW) is not impeded. 
However, since Bugbyter is constantly updating the Master Display 
when you are in Trace or Single-Step mode, you are not likely to 
see any of your program's output. 


Eliminating this contention between Bugbyter and your program 
for the use of the Apple II's text screen is a simple matter. From the 
Bugbyter command level, just type 


JFF 


and press (RETUAN). Bugbyter clears the first 23 lines of the text 
page, leaving the command prompt appearing on the lowest line. 
When you enter Trace or Single-Step mode, Bugbyter allows your 
program to write anything it desires to this text page. 


To recall the Master display from the Bugbyter command level, 
simply type 
ih 


and press (RETURN) in response to the Bugbyter command prompt. 
lf you are currently in Trace or Singie-Step mode, press (ESCAPE) 
first to exit to the Bugbyter command level. 


Eliminating Keyboard Contention 


When your program requires input from the keyboard, you want to 
make sure that Bugbyter does not interfere with your program's 
polling of the keyboard. Normaily in Trace or Single-Step mode, 
Bugbyter samples (polls) the keyboard to respond when you type 
one of the single-keystroke commands. If you are tracing or single- 
stepping a program that expects input from the keyboard, your 
program never receives any characters unless you turn off 
Bugbyter’s keyboard polling. 


When you turn off keyboard polling, Bugbyter ignores all 
characters typed at the keyboard except one special interrupt 
character that you specify. Bugbyter scans the keyboard address 
($C000) during Trace or Single-Step mode, but does not clear the 
Keyboard-Ready flag unless the character you type is this special 
interrupt character. For any other characters, Bugbyter leaves 
these addresses intact and permits your program to accept the 
keystroke from the keyboard input register. 
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Soft switches: see the section 
"Debugging Real-Time Code." 


(G) on the Apple Ile's keyboard 
functions exactly as hand control 
button 0; if you have an Apple Ile, you 
can use hand control button 0 and 
interchangably. 
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To turn off Bugbyter’s keyboard polling, you must set Bugbyter’s 
Keyboard-Polling soft switch. 


The Keyboard-Polling soft switch is located at memory location 
$7CO6. If you relocate Sugbyter to a different address, the 
Keyboard-Poiling soft switch is located at the sixth location 
following the start of the Bugbyter. The byte stored at this location 
consists of 


è aone-bit Keyboard-Polling flag, the most significant bit 


è a seven-bdit ASCII value that defines a special interrupt key 


When you first start Bugbyter, this most significant bit is a zero. If 
you set this keydoard-poiling flag to 1, Sugbyter turns off its 
keyboard polling when in Trace or Singie-Step mode. With 
keyboard polling turned off, Bugbyter continues to scan for the 
special interrupt keystroke that you specified. For example, if you 
type 


a 
rl 


PITH 3! 


V1 

from the Bugbyter command level and press (RETURN), it turns off 
Bugbyter’s keyboard polling in Trace mode and instructs Bugbyter 
to scan for a (CONTROL)-(A) ($01) character. The program you are 
debugging then can accept any keystroke from the keyboard 
except the character. When you press (CONTROL)-(A) 
in Trace mode, Bugbyter exits from Trace mode and returns you to 
the Bugbyter command level. 


Using Hand Controi Button 0 to Control Trace Mode 


Rather than have Bugbyter scan the keyboard during Trace mode, 
another way to communicate with Bugbyter in Trace mode is to 
use hand control button 0. This technique frees the keyboard so 
your own program can accept any keyboard character as input. 


To use hand control button 0 to suspend Bugpbyter’s Trace mode, 
you must activate this feature before you enter Trace mode. 
Pressing hand control button 0 does not cause Bugbyter to exit 
Trace mode, as does pressing or typing the interrupt key 
when Bugbyter’s keyboard polling is turned off. Instead, when this 
feature is activated and you are in Trace mode, hand control 
button 0 suspends Bugbyter’s trace of your program; Bugbyter 
continues tracing as soon as hand control button 0 is released. 
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To set up this feature, you must set Bugbyter’s soft switch 

to $80—normally, this soft switch is cleared or $00. It is located at 
memory address 7C04 (or at start+4 if you have relocated 
Bugbyter to a different memory location). To set this soft switch, 
type 


Trad: Se 


and press (RETURN). 


oo 
are 


lf you set the hand-control-button-0 soft switch to $80 and you have 
not connected hand control 0 to your Apple II's GAME 1/0 port, your 
Apple II will be “frozen” if you enter Bugbyter’s Trace mode. This is 
because your Apple |! sees a disconnected hand control as a hand 
control with the button continually depressed. 


This does not happen if you are using an Apple lle, since is a 
permanently connected hand control button 0. 


Using Hand Control 0 


You can use hand control 0 to control Bugbyter’s trace rate when 
you are in Trace mode. To activate this feature, simply type (P). 
To deactivate this feature and cause Bugbyter to return to using 
the keyboard trace rate (shown under the A label in the Register 
subdisplay), type while you are in Trace mode. 


lf you are debugging a program that itself uses hand control 0, you 
may want to disabile this feature, causing Bugbyter to ignore a (P) 
keystroke when you are in Trace mode. To disable Bugbyter’s use 
of hand control 0, you must clear Bugbyter’s hand-control-0 soft 
switch, located at memory address 7C06 (or at start+6 if you 
relocated Bugbyter). Type 


A 
i 


a. 


le, 


A 


iT, 


and press (RETURN), to clear this soft switch. 


To have positive control over Bugbyter’s use of all three of your 
Apple II's input devices, you can set or clear the hand-control-button- 
0, hand-contol-0, and the keyboard-polling soft switches ail at once. To 
disable Bugbyter’s use of the hand controls and to activate Bugbyter’s 
keyboard polling, you can clear all three of these soft switches at once 
by typing 

TCH4;88 6 


and pressing (RETURN). 
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Soft switches: memory locations at the 
start of the Bugbyter program code that 
you can set or clear to control features 
of the Bugbyter. 
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Executing Undefined Opcodes 


When you are debugging your program in Trace or Single-Step 
mode, Bugbyter ignores any illegal or undefined 6502 instruction 
opcodes. You can disable this restriction using a Bugbyter soft 
switch. 


To allow Bugbyter to execute undefined 6502 opcodes, you must 
set the byte at relative location start +3 (absolute location $7C03 if 
the Bugbyter was loaded at address $7C00) to $80 (this byte is 
initially $00 when Bugbyter is first loaded). To prevent Bugbyter 
from executing illegal 6502 instruction opcodes, you must reset 
this location to $00 using Bugbyter’s normal memory assignment 
commandas. 


Since Bugbyter does not know the length of an undefined 
opcode's operand, Bugbyter assumes no operand and increments 
the 6502 program counter by one. You must use (—) in Single- 
Step mode to skip past any operands to the next instruction. Using 
the complete register and memory display capabilities of 
Bughyter, you can easily explore all of the undefined operations of 
the 6502 (try executing AF 58 FF, for example). 
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You can read more about the BLOAD 
command in the DOS Programmer's 
Manual. 
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The Relocating Loader 


The Relocating Loader routines in this tool kit are tools that allow 
you to run your assembly-language subroutines from within BASIC 
programs, and that allow these BASIC programs to run efficiently 
on Apple |i systems with varying amounts of memory. 


There are two ways that you can run an assembly-language 
subroutine from a BASIC program: 


è You can use the DOS BLOAD command to load your binary 
object file into memory, then call your routine using the fixed 
starting address at which your program is assembled. 


e Asan alternative, you can use the Relocating Loader routines to 
load your relocatable object program just below the Apple Il’s 
HIMEM address. This second alternative may boe more 
attractive because it allows your BASIC program to run 
effeciently on Apple |i systems having varying amounts of 
memory. 


This chapter explains how to use the Relocating Loader routines. 


è The first part of this chapter explains what the Relocating 
Loader routines are and what they do. 


è The second part of this chapter explains how you can use these 
routines from within a BASIC program. 


You may need to read this chapter only if you want to use your 
assembly-language programs as part of an Applesoft BASIC 
program. 
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iin /niroduction to the Relocating Loader 


The Relocating Loader routines only 
load relocatable assembly-ianquage 
modules (R files) that you generate 

using the Assembler’s REL directive. 


REL assembly directive: see Chapter 3. 





160 


The Relocating Loader consists of two routines, RBOOT and 
RLOAD. Together, these two routines allow your BASIC programs 
to load relocatable assembly-language subroutines into high 
memory, without regard to the amount of memory contained in 
your particular Appie II system. After your BASIC program has 
loaded your assembly-lanquage subroutines, your BASIC program 
can call these subroutines at any time. 


To use the Relocating Loader, your BASIC program must first 
BLOAD and then call the RBOOT routine from BASIC. This RBOOT 
routine loads and sets up the RLOAD routine, which performs the 
actual relocation of your assembly-language modules. Once you 
call the RBOOT routine, your BASIC program can call the RLOAD 
routine to load your individual relocatable subroutines into 
memory. After loading each relocatable subroutine into memory, 
the RLOAD routine returns an address at which your BASIC 
program can later call the actual assembly-language subroutine to 
perform its particular function. 


When you cail the RLOAD routine to load your assembly-language 
modules, RLOAD loads the designated module just below the 
HIMEM address of your Apple || system. RLOAD then reduces this 
HIMEM address to just below the first byte of the module that was 
just loaded, effectively hiding this block of code from being 
overwritten by Applesoft. You can load as many relocatable 
modules in this fashion as you like, as long as there is sufficient 
memory available for RLOAD and at least one free DOS file buffer. 


The Relocating Loader routines do not constitute a linking loader. 
Although you can use these routines to load as many assembly- 
language modules as you like, the Relocating Loader will not 
resolve inter-module references or external symbols that you may 
have defined using the Assembier’s EXTRN or ENTRY pseudo-op 
directives. Typically, if you use more than one assembly-language 
module in your BASIC program, you must call each module 
separately from Applesoft. 





Restrictions on Using the Relocating Loader 


You can use the Relocating Loader routines with almost any 
BASIC program. There are several restrictions on how you can use 
these routines, and, in particular, on when you can use them. 
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Numeric variables can be used before 
your program calls the Relocating 
Loader: see the example in Figure 5-1. 


Figure 5-1. Using RBOOT and RLOAD 
Routines in Your BASIC Program 


Note that you cannot use the usual DS 
for the DOS BLOAD command; you 
must instead use a CHRS(4), because 
you cannot allocate string variables 
before using the RBOOT and RLOAD 
routines. 





è Before calling the Relocating Loader, your program must not 
allocate or use any string variables. The RLOAD routine does 
not attempt to save any string data that your program allocated 
before RLOAD loads relocatable modules into memory. 


e After calling RBOOT, your program must not Dimension or 
allocate any new numeric or string variables until after the last 
usage of RLOAD to pull in your relocatable modules. Any 
variables that you use during this process must be allocated 
before your program calls RBOOT (see the example in 
Figure 5-1). This restriction is necessary since the-RBOOT and 
RLOAD routines occupy memory just above Applesoft’s 
variable tables. After you use RLOAD for the last time, you are 
free to allocate new BASIC variables that overwrite the RLOAD 
routine and reuse this memory space. 


Using the Relocating Loader 


To call the Relocating Loader from a BASIC program, your 
program must first load and execute the RBOOT routine from 
Applesoft BASIC. Figure 5-1 shows the syntax of the BASIC 
statements that call the Relocating Loader routines. 


The following example shows the syntax of the BASIC statements 
that call the Relocating Loader routines and load a relocatable 
module called MYMODULE from a disk: 


1H ADRS =; FEM PRE-ALLOCATE AORS VARIABLE 


SA PRIHT CHREC¢42;: "BLOAO ROOT": CALL 328: REM 
LOAD $ CALL REDOT 


3A AOR SSUSR CRD, UMYMCOOULE, 36,01" : REM LOARO 
RELOCATAELE MOOWLE 


LL 


Calling RBOOT 


The RBOOT routine is a small subroutine that you must BLOAD 
into addresses $208 through $3CF and then call by executing a 
CALL 520 from BASIC. 


When you call RBOOT to load the RLOAD routine into memory, 
RBOOT loads the RLOAD routine above the end of APPLESOFT's 
variable tables. RBOOT accepts no parameters, but assumes that 
the RLOAD function is on the disk that was last accessed, which 
typically is the disk from which RBOOT itself was just BLOADed. 
The RBOOT routine then sets up the USR(0) function with the 
starting address of RLOAD. 
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Using RLOAD 

Once you call RBOOT, your BASIC program can call the RLOAD 
routine to load relocatable modules by calling the USR(0) function. 
The RLOAD function takes three parameters from the statement 
containing the USR(Q) function: 

e the DOS filename of the module to be loaded 


‘® an optional siot and drive number. 


These parameters must be inside a quoted literal and may be 
separated from the USR function by a comma. The filename is 
required, although the siot and drive parameters are optional. If 
the filename is omitted, aF ILE NOT FOUNO error code is 
returned. The filename must be the name of a REL type file, not a 
binary file. The slot and drive parameters can appear in either 
order or can be omitted. 


The RLOAD routine either returns the load address of the 
relocatable module that you loaded, or returns an error if it 
encounters a problem while attempting to load your module. You 
can catch this error by using Applesoft’s ON ERR facility. If you do 
not use the ON ERR statement prior to using RBOOT and RLOAD, 
and RLOAD encounters an error while trying to load your module, 
your program does not function correctly. 


The value returned by the USR function is a signed Real result that 
your program can later use to Cail the loaded module. This 
obviously assumes that your relocatable module begins with an 
executable code segment. 


An effective means of providing multiple entry points to your 
relocatable module is to put a table of jump instructions at the 
Start of the module. This allows your BASIC program to execute 
CALLs to the returned ADRS, ADRS +3, ADRS +6, ADRS +9, and 
so forth, as a means of entering the various subfunctions in your 
module. This technique also allows the contents of your 
relocatable module to grow or shrink later and not disturb your 
BASIC program's interface to the assembly-language module. You 
can later add additional jumps to the table for new functions, while 
not disturbing the existing interface to your original entry points. 
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You can load as many modules as you wish, up to the available 
memory space minus the size of RLOAD itself. RLOAD is about 
1.5K in length and always loaded on a page boundary by RBOOT. 
RLOAD requires at least one free file buffer available that it can 
borrow from DOS. If there is no free buffer, a HŪ BUFFERS 
AWAILABLE error occurs. — 


Since RLOAD reduces the address of HIMEM when it loads a module, 
you should save the initial value of HIMEM by Peeking it out of zero 
page, so that you can later restore this setting when your program 
finishes executing. The Relocating Loader does not automatically 
restore HIMEM to its original setting. 





Warning 

When you are testing a program that uses the Relocating Loader, you 
should be aware that repeated use of RLOAD without restoring HIMEM 
causes RLOAD to allocate new space each time that it loads a module. 
This can eat up all of memory in short order if you do not restore HIMEM 
to its normal value before each test. An easy way to test such a program is 
to issue an FP command to DOS, and then Run the program from the 
disk. Be aware that the FP command erases the program currently in 
memory. This can cause you to execute extra Saves during the testing 
process, but saving your program occasionally is a good practice anyway. 
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if you are only writing programs that you 
will use yourself, you may not need to 
read this chapter. 


For information about using the 
identification Routines in BASIC 
programs, see the corresponding 
chapter in the Applesoft/DOS 
Programmer's Tool Kit. 
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Chapter 6 


The Apple lle System 
Identification Routines 


The Apple lle System Identification routines in this tool kit allow 
your assembly-language and BASIC programs to identify the type 
of Apple |! system on which they are running. If you intend to write 
programs that might eventually run on different Apple || systems, 
then you might consider using these routines in your program. 


When you incorporate a System Identification routine into your 
program, your program can identify whether it is currently running 


‘on an Apple ll, an Apple Ii Plus, or an Apple lle computer. If your 


program is running on an Apple lle system, these routines aiso 
identify the additional accessory cards that are currently installed, 
such as the Apple Ile 80-Column Text Card, or the Appie lle 
Extended 80-Coiumn Text Card. 


Using this information, your programs can take advantage of all 
the capabilities of the more powerful Apple II systems, while still 
maintaining compatibility with the whole family of Apple |! 
computer systems. 


This chapter explains what the Identification Routines can do, and 
describes how you can use these routines in your assembly- 
language programs. It specifically 


@ introduces the Identification Routines and explains the 
information that this routine can return to your program; 


è explains how you can incorporate these routines into your 
assembly-language programs; 


e gives an overview of the identification procedure, if you want 
only to incorporate portions of the identification routines in your 
program. For your convenience in customizing or expanding the 
identification routines, assembly-language source code for the 
identification routines is included in this tool kit. This section 
serves as documentation for the accompanying source code. 
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Rae troduction to the Identification Routine 


Table 6-1. identification Procedure 
Return Values 
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The Apple lle System Identification Routine provides a standard 
way of identifying the various configurations of the Apple Il. These 
routines are intended for both professional and amateur 
programmers: anyone who is writing programs that might run on 
more than one Apple || system. Since your particular program may 
not need all the parts of the complete identification routine, this 
tool kit includes the source code for both the assembly-language 
and BASIC versions of this program. 


You have a number of files on the DOS Programmer’s Tool Kit 
Volume || disk related to the Apple || System Identification 
routines. These files are 


è All ASSEMBLY |D.S—the assembly-language source code for 
the Apple || System Identification routine 


e All ASSEMBLY !D—the machine-language (binary) version of 
these routines. 


When you call the identification routine from your assembly- 
language program, the identification routine returns a single value 
that identifies the type of Apple || system on which the program is 
executing and the capabilities of that system if it is an Apple lle. 
Table 6-1 shows the possible values that may be returned and the 
corresponding machine configurations that these values indicate. 


Returned Vaiue Your System Configuration 

$00 _An Apple Ii or Appie |i Plus 

$20 An Apple lle that does not have an 80-Column Text Card 
$40 An Apple ile with an 80-Column Text Card 

$80 An Apple lle with an Extended 80-Column Text Card 


Using the Routines in Your 
Assembly-Language Programs 


The most efficient way to incorporate the Apple || System ID 
routines into your assembiy-language programs is simply to 
include the AIIE ASSEMBLY ID.S source file into your own 
program source file using the Assemblier’s INCLUDE directive. A 
second alternative is to use the Editor to append your program's 
source file with the All ASSEMBLY ID.S source statements to 
create a single file containing both modules. In either case, when 
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you assemble your source file, you automatically incorporate the 
Apple |i System ID routines into your program. Only slight 
modifications to the All ASSEMBLY !D.S source text are required 
to make this module a subroutine within your main program. 


The binary code file All ASSEMBLY ID is a machine-language 
subroutine that starts at location $2D4 and occupies memory from 
location $2D0 to $3CF. If you are not using the Editor/ Assembler 
to develop your application program, there is yet another way to 
link the Apple II System ID routine into your program. If you 
BLOAD both your main program and then the All ASSEMBLY ID 
(machine-language version), you can then BSAVE both modules 
together on the same disk file. Your main program must call the 
identification routine using a JSR to location $2D4, and then 
retrieve the identification code from location $3CF once the 
identification routine returns control to your calling program. 


Overview of the Identification Procedure 


This section contains an overview of the procedure that the 
identification routines go through to identify the particular Apple || 
configuration on which your program is running. 


For some programs, you may not need to identify the exact 
configuration of your computer. For example, your program may 
not use auxiliary memory and you may not care to waste code 
space or execution time to find out if this memory is installed. For 
these reasons, you may wish to modify these identification 
routines. If you do this, however, Apple PCS Product Marketing 
Technical Support requests that your altered programs determine 
the Apple || configurations in the same way as the identification 
routines included here. Future revisions of the Apple Ile may not 
be compatible with other identification procedures. 


The following is a list of the steps carried out by the Apple lle 
identification routine as it determines the configuration of your 
Apple II system: 


1. Save four identification bytes from the ROM/RAM area ($D000 
to $FFFF). 


2. Disable interrupts. 


3. Switch bankable memory to read ROM by reading $C089 
twice. 


4. Identify Apple lle by finding the number 6 at $FBB3. 
5. If it is an Apple lle and the high bit is on at location $C017, 
then it has an 80-column text card. 
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6. If it is an Apple lle with an 80-column text card, then check for 
auxiliary memory: 


e if $C013's high bit is on, then it is reading auxiliary memory 
so it must have auxiliary memory. 


è If $C016's high bit is on, then it is reading alternate zero 
page so it must have auxiliary memory. 


è |f sparse memory mapping (no upper four address bits so 
that $800 has the same RAM location as $C00), then it has 
no auxiliary memory. 


a. 


g. 
h. 


Exchange a section of zero page with the section of code 
that switches memory banks. This way the zero page 
data is saved and the program doesn’t get switched out. 


. Jump to the relocated code on zero page. 


. Switch in auxiliary memory ($200-$BFFF) for reading and 


writing by writing to $CO05 and $C003. Note: Auxiliary 
memory locations $400-$800 and $2000-$4000 may not 
be available depending upon the setting of soft switches 
for 80-column video display and high-resolution 
graphics; they have priority over auxiliary memory 
selection. 


. Store a value at $800 and see if the same value is at 


$COO; if not, then there is auxiliary memory. 


. Change the value at $C00 and see if $800 changes to the 


same value; if so, then there is no auxiliary memory. 


. Set soft switches for reading and writing to main memory 


by writing to $C002 and $C004. 
Jump back into program on main RAM. 


Put zero page back. 


7. Store identification byte for later reference by calling routine. 


8. Restore the RAM/ROM area to its original state by checking 
four bytes saved at the start of the routine. 


9. Enable interrupts. 


10. Return to calling program. 
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An Editor Quick Guide 


Ms §$Edjtor Commands: A Functional Summary 


Editor Command Form Command Description 





Executing Direct DOS Commands 


.doscommand Issues the characters after the 
period to DOS 3.3 to be 
processed as a DOS 
command. DOS checks the 
syntax and issues any 
required error messages. 





Storing and Retrieving Files From a Disk 


LOAD fname [,Ss] [,Dd] [,Vv] Loads the file with fname into 
the text buffer, destroying 
anything already in the buffer. 


APPEND [line#] fname [,Ss] Appends ail the lines of fname 
[,Dd] [, Vv] to the text buffer after [line=]. 
SaVE [begins [-end=]] [fname] Saves the lines [in the indicated 
[,Ss] [,Dd] [, Vv] range] to the file named 
fname. 
CATalog [,Ss] [,Dd] [, Vv] Displays the DOS catalog of the 


disk in the current SLot, 
DRive, and Volume. 

FILE Displays the current status of 
the Editor’s filename, SLot, 
DRive, and Volume 
parameters along with the 
text buffer memory usage 
totals. 

LENgth Displays the current text 
buffer’s file usage totals. 
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SLot siot# Sets the current disk SLot to 
slot#. 

DRive drive# Sets the current disk drive to 
drives. 

Volume vol#+ Sets the current volume 


number to vol#. 





Manipulating Lines in the Text Buffer 


Add [line#] Adds lines [after line#] to the 
text buffer. Enters Input 
mode to add the new lines. 

Insert line Inserts lines from the keyboard 
before line#. Enters Input 
mode to insert the new lines. 


COpy line# 1 [-line#2] TO Copies line#1 [thru line=2] to 
line#3 before line#3. 
Delete begin# [-end#] Deletes the range of lines from 
the buffer. 
Replace begin# [-end#] Deletes the range of lines and 


enters Input mode, like 
Insert, to add new lines to the 
text buffer in place of the 
deleted lines. 

NEW Deletes the entire contents of 
the text buffer. 





Viewing Your Text in the Text Buffer 


List [begin [-end#]] Displays, with line numbers, the 
lines in the indicated range 
within the text buffer. Control 
characters display in inverse 


video. 

(CONTROL)-(R) Relists the lines of text listed by 
the most recent List 
command. 

Print (begin# [-end#]] Outputs, without line numbers, 


the lines within the indicated 
range. Control characters are 
output as control characters. 
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Changing Text Within a Line 


Find [beginz [-end#]] [.string.] Displays ail lines within the 
indicated range that contain 


: the string. 
Change [begin# [-end#]] Changes All/Some of the 
-Oldstr.newstring. occurrences of a string 


(oldstr) to a new String 
(newstr) within the range of 
lines indicated. 

Edit [begins [-end#]] [.string.]° Enters Edit mode for all lines 
indicated [that contain the 
String]. 

SET Delim .char. Changes the Editor command 
delimiter character to the 
new character indicated. This 
permits the colon character 
to be used in a search String. 


Editing Two Files at Once 


SWAP Swaps the currently-active text 
buffer, Saving the contents of 
the current one for later 
editing. 

KILL2 Deletes the entire contents of 
text buffer 2 and returns to 
Single text buffer mode with 

text buffer 1. 


Altering the Display 


COLumn 40 Sets the Editor display routines 
to 40-column display mode. 
COLumn 80 Sets the Editor display routines 


to 80-column display mode, if 
your Apple II can Support 
this. 

(CONTROL)-(E) Enables lowercase character 
entry (only for Apple II or 
Apple II Plus systems that 
cannot otherwise receive 
lowercase characters). 


(CONTROL)-(W) Disables lowercase character 


entry that was enabled by 


(CONTROL)-(E) command. 
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SET Lcase Enables lowercase character 
entry (for Apple Il or Apple II 
Plus systems that do not 
contain an ALS Smarterm 
Card, but can receive and 
display lowercase 
characters). 

SET Ucase Disables lowercase character 
entry that was enabled by the 
SET Lcase command. 

Tabs [Tablist] [.tabchar.] Sets the Editor dispiay tabs 
stops to the Tablist and sets 
the tab character to tabchar. 


TRuncON Turns on comment display 
truncation. 

TRuncOFf Turns off comment display 
truncation. 


—— ae 


Leaving the Editor 


END Ends the Editor session and 
' returns control to the BASIC 
interpreter. 
MON Enters the Apple |i Monitor. 


(Type (CONTROL)-(Y) to return 
to the Editor.) 

Where line# Displays the hexadecimal 
address of text for line# 
(address useful when using 
Monitor commands). 








Calling the Assembler 

PR# slot# [,DevCtristrg] Sets the Assembler output 
device to slot (slot+) and 
saves the DevCtristrg for 
device initialization by the 
Assembler. 

ASM srcfile [, @, objfile(,Ss{,Dd Calls the Assembler to 

[,Vv]]] assemble the source file 


(srcfile) and create an object 
file (objfile) on Slot s, Drive d, 
Volume v. 
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Command Description 


Editor Command Form 


Add [line#] 


APPEND [line#] fname [,Ss] 
(,Dd] [, Vv] 
ASM srcfile [, @, objfile [,Ss [,Dd 


(,Vv]]] 


CATalog [,Ss] [,Dd] [, Vv] 
COLumn 40: 


COLumn 80 


(CONTROL)-(E) 


(CONTROL)-(R) 


(CONTROL )-(W) 


Change [begins [-end=]] 
.oldstr.newstring. 


COpy line#1 [-line=2] TO 
line#3 
Delete begin= [-end#] 
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Adds lines [after line=] to the 
text buffer. Enters Input 
mode to add the new lines. 

Appends all the lines of fname 
to the text buffer after [line=] 

Calls the Assembler to 
assemble the source file 
(srcfile) and create an object 
file (objfile) on Slot s, Drive d, 
Volume v. 

Displays the DOS catalog of the 
disk in the current SLot, 
DRive, and Volume. 

Sets the Editor display routines 
to 40-column display mode. 
Sets the Editor display routines 
to 80-column display mode, if 

your Apple IlI can support 
this. 

Enables lowercase character 
entry (only for Apple |! or 
Apple || Plus systems that 
cannot otherwise receive 
lowercase Characters). 

Relists the lines of text listed by 
the most recent List 
command. 

Disables lowercase character 
entry enabled by 
(CONTROL)-(E ) command. 

Changes All/Some of the 
occurrences of a string 
(oldstr) to a new string 
(newstr) within the range of 
lines indicated. 

Copies line#1 [thru line=2] to 
before line#3. 

Deletes the range of lines from 
the buffer. 
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.DOS Command 


DRive drive# 
Edit [begin# [-end#]] [.string.] 
END 


FILE 


Find [begin# [-end#]] [.string.] 
Insert line# 
KILL2 


LENgth 


List [begin# [-end#]] 


LOAD fname [,Ss] [,0d] [, Vv] 
MON 


NEW 
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Issues the characters after the 
period to DOS 3.3 to be 
processed as a DOS 
command. DOS checks the 
syntax and issues any 
required error messages. 

Selects the current disk drive 
for use by the Editor disk |/O 
commands. 

Enters Edit mode for all lines 
indicated (that contain the 
string]. 

Ends the Editor session and 
returns control to the BASIC 
interpreter. 

Displays the current status of 
the Editor’s filename, SLot, 
DRive, and Volume 
parameters along with the 
text buffer memory usage 
totals. 

Displays all lines within the 
indicated range that contain 
the string. 

Inserts lines from the keyboard 
before line#. Enters Input 
mode to insert the new lines. 

Deletes the entire contents of 
text buffer 2 and returns to 
single text buffer mode with 
text buffer 1. 

Displays the current text 
buffer’s file usage totals. 

Displays, with line numbers, the 
lines in the indicated range 
within the text buffer. Control 
characters display in inverse 
video. 

Loads the file with fname into 
the text buffer, destroying 
anything already in the buffer. 

Enters the Apple |i Monitor. 
(Type to return 
to the Editor.) 

Deletes the entire contents of 
the text buffer. 


Print [begin# [-end#]] 


PR# slot# [,DevCtristrg] 


Replace begin# [-end#] 


SaVE [begin# [-end#]] [fname] 
[,Ss] [,Dd] [,Vv] 


SET Delim .char. 


SET Lease 


SET Ucase 


SLot slot# 


SWAP 


Tabs [Tablist] [.tabchar.] 


TRuncOFf 


TRuncON 





Outputs, without line numbers, 
the lines within the indicated 
range. Control characters are 
output as control characters. 

Sets the Assembler output 
device to slot (slot+) and 
saves the DevCtristrg for 
device initialization by the 
Assembler. 

Deletes the range of lines and 
enters Input mode, like 
Insert, to add new lines to the 
text buffer in place of the 
deleted lines. 

Saves the lines [in the indicated 
range] to the file named 
fname. 

Changes the Editor command 
delimiter character to the 
new character indicated. 
(Permits the colon character 
to be used in a search string). 

Enables lowercase character 
entry (for Apple |i or Apple ll 
Plus systems that do not 
contain an ALS Smarterm 
Card, but can receive and 
display lowercase 
characters). 

Disables lowercase character 
entry that was enabled by the 
SET Lcase command. 

Sets the current disk SLot to 
slot#. 

Swaps the currently-active text 
buffer, saving the contents of 
the current one for later 
editing. 

Sets the Editor display tabs 
stops to the Tablist and sets 
the tab character to tabchar. 

Turns off comment display 
truncation. 

Turns on comment display 
truncation. 
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Volume vol# 


Where linet 





Sets the current volume 
number for use in the disk |/O 
commands. 

Displays the hexadecimal 
address of text for line#. 


Edit Mode Keystroke Summary 


Editing Function 


Move cursor left one character 

Move cursor right one 
character 

Delete current character 

Insert characters at this 
position 

Replace a character 

Enter control character into text 
(Verbatim) 

Restore the original line 

Find the indicated character in 
the line and move the cursor 
there 

Store line as it appears on 
screen 

Truncate line after current 
cursor and store the 
remainder in text buffer 

Cancel Edit mode and return to 
command level 
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Edit Mode Keystroke 
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(CONTROL )-(0) 
(CONTROL )-(1 ) 


any noncontrol character 
(), any character 


(CONTROL)-(R) 
(CONTROL)-(F), any character 


(CONTROL)-() 


(CONTROL)-(x} 
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6502 Assembly 
Language Summary 


Ree Mnemonic Summary 


Mnemonic instruction 

ADC A+M+C->A 

AND AandM->A 

ASL C <- [7..0] <-0 

' BCC Branch on C = 0 

BCS Branch on C = 1 

BEQ Branch on Z = 1 

BGE Branch on C = 1 

BIT A and M, M7 -> N, M6-> V 

BLT Branch on C = 0 

BMI Branch on N = 1 

BNE Branch onZ = 0 

BPL Branch on N = 0 

BRK Force Break 

BVC Branch on V = 0 

BVS Branch on V = 1 

CLC 0->C 

CLD 0->0D 

CLI 0 ->| 

CLV 0 ->V 

CMP ÀA - M status -> P 
q CPX X - M status -> P 

CPY Y - M status -> P 

DEC M-1->M 

DEX X-1->X 

DEY ¥st-> yY 

EOR A xor M -> A 

INC M+1->M 

INX X+1->X 

INY Y+1-+>Y 
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JMP Jump to New Location 


JSR Jump to Subroutine 
LDA M->A 

LDX M ->X 

LDY M ->Y 

LSL C <- [7..0] <- 0 

LSR 0 -> [7...0] -> C 

NOP No Operation (PC =PC + 1) 
ORA MorA->A 

PHA A -> Ms S-1->S 

PHP P -> Ms S-1->S5 

PLA S$+1->S Ms->A 
PLP S$+1->S Ms->P 
ROL '-<— [7.0] <— C <—' 
ROR > G —> [7.0] —>-’ 
RTI Return from interrupt 
RTS Return from Subroutine 
SBC A-M-C->A 

SEC 1->C 

SED 1->D 

SEI 1->l| 

STA ’ A ->M 

STX X ->M 

STY Y ->M 

TAX A ->X 

TAY A ->Y 

TSX S->X 

TXA X->A 

TXS X -> S 

TYA Y ->A 

where 


A, X, Y, S, and P are the 6502 registers 

M is a memory location 

C is the Carry bit of the P-register 

+ indicates binary addition 

[7...0] is a bit description of M or A 

Ms indicates the location to which the S-register points. 
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See the Preface, section ‘Reference 
Manuals on the 6502 
Microprocesssor.” 
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iii ene Addressing Mode Summary 


Note that all required syntax may be preceded by an optional 
identifier in the label field of a statement. 


Addressing Mode 


Implied (no address) 
Accumulator 
Immediate 

Low 8 bits of address 

High 8 bits of address 
Zero page 

Indexed X 

Indexed Y 
Absolute 

Indexed X 

Indexed Y 
Indexed, indirect X 
indirect, Indexed Y 
Absolute indirect 


where 


Required Syntax 


opc 
opc A 

opc #expression 

opc #>expression 
opc +<expression 
opc zpg-expression 
opc zpg-expression,X 
opc zpg-expression,Y 
opc abs-expression 
opc abs-expression,X 
opc abs-expression,Y 
opc (zpg-expression,X) 
opc (zpg-expression),Y 
JMP (abs-expression) 


opc refers to an instruction mnemonic 
abs refers to an absolute address expression 
zpg refers to a zero-page address expression. 


All other characters must be typed as shown. 


By the Way: in zero-page address expressions, the expression result 
must either be less than 256, or you must use the low-byte 
operator (>) in front of the expression to indicate a single-byte result. 


This is only a summary. Please refer to the 6502 Programming 
Manual, published by the manufacturers of the 6502 
microprocessor, for complete details. 


Assembler Directive Summary 


Directive Syntax Format 


ASC .string. 
CHN filename 
[ [slot][,[drivel][, vol]]] 
CHR /? 
DATE 
DCI .string. 


Assembler Directive Summary 


Directive Description 


ASCII character data 
Chain to new source file 


Character used for REPeat 


DATE character data (9) 
special ASCII character data 
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DOB expr{,expr...] 
DEF identifier 
DEND 

DFB expr{,expr...] 
DO expr 

DS expr{[,expr] 
DSECT 

DW expr{[,expr...] 
ELSE 

ENTRY identifier 
identifier EQU expr 
EXTRN identifier 
FAIL p,.string. 

FIN 

IBUFSIZ expr 
IDNUM 

IFEQ expr 

IFGT expr 
IFNE expr 

IFLT expr 
INCLUDE 

filenamef[,[{siot][,[drive][, vol] 
LST [ON, OFF] 

[, [NOJopt(,[NO]oot...]] 
MACLIB (siot]{,[drive][, voll] 
MSB [ON , OFF] 

OBJ expr 

ORG expr 

PAGE 

REF identifier 

REL 

REP expr 

SBTL .string. 

SBUFSIZ expr 

SKP expr 

STR .string. 

SW 16 [expr] 

ZDEF identifier 

ZREF identifier or ZXTRN 
identifier 


IFGE expr 


IFLE expr 





Define Double Byte 

Define absolute identifier 
Dsect END 

DeFine Byte(s) 

DO assembly if expr > 0 
Define Storage [value] 
Dummy Section beginning 
Define Word(s) 

complement Assembly mode 
define ENTRY identifier 
EQUate identifier to expr 
Refer to external identifier 
FAlLure error message 
FINish conditional assembly 
Set INCLUDE-buffer size 
generate IDNUM data (6 bytes) 
begin conditional assembly 


begin conditional assembly 
INCLUDE file into source 
Control listing options 


Macro library disk enable 
Most Significant Bit set 
OBJect memory address set 
Origin of Assembler adrs 
eject a PAGE on listing 
REFerence global identifier 
generate RELocatabie output 
Repeat CHR expr times 
define subtitle string 

Set source-buffer size 

SKip expr blank lines 
counted ASCII string data 
call SWEET 16 interpreter 
Zero-page global definition 
Zero-page external reference 


6502 Assembly Language Summary 


a eS. a Youd oe ee S = 
iat ik- iz rT a i ne, P IRAN ; 
Sa a Heas e wena’? Sie SA A 
ST ee Sra oS iae pen ew Pe! ma, 
| 2 bee ae z «Yt Ss c 


à Sa ; a a2 . p t- 
Sees are ete eae ss r Š 


na 
ae ae | 4 . 

a Dat TS RR 

Se a he a A 





A Bugbyter Quick Guide 





Bugbyter Command Level 
General Commands 
.doscommand Execute DOS command. Press to 


return to Bugbyter. 


(Q) Quit Bugbyter (exits through DOS vector 
$3D0). 
(M) Enter Monitor. Return to Bugbyter with 
(CONTROL)-(¥ ). 
address Disassemble object code beginning at 
address. 
Continue disassembling object code. 
SET Customize Bugbyter’s Master Display, where: 
=) Moves window down. 
=) Moves window up. 
Fixes subdispiay and advances 
to next subdisplay. 
ON Turn Bugbyter’s Master Display on. 
OFF Turn Bugbyter’s Master Display off. 
Display copyright and version number. 





Command-Line Editing 


Keystroke Editing Function 

RETURN Accept user-entered command line. 

(—) Move cursor to the left. 

=) Move cursor to the right. 

(CONTROL)-(8) Move cursor to beginning of command line. 
(CONTROL)-(C ) Accept next keystroke verbatim. 

(CONTROL )-(0 ) Delete a character. 
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(CONTROL)-(1 ) 


(CONTROL)-(N) 
(CONTROL)-(X) 


Memory Reference 


MEM 


address:mnemonic 
or address:vaiue 
or address:'‘‘text”’ 


or address: ‘text’ 
or (any mixture) 


address: 


+ decimalvaiue= 
— decimailvalue= 


value= 
$value = 


Œ) 
(P) 


address 


m 
or (SPACE) 
or 
a 





Enter insert-character mode (any other 
function key exits from this mode). 
Move cursor to end of command line. 
Delete command line. 





Edit memory subdisplay where: 

Display contents of address as 
hex and ASCII, or 

Display contents of address 
and address + 1 as pointer. 

Enter hex address of memory to 


display. 


line. 


Bugbyter assembles mnemonic, placing 


opcode at address. 


Fill address with hex value. 

Fill address with ASCII character (MSB on). 
Fill address with ASCII character (MSB off). 
Multiple values and ASCII text (MSB on or 
off) can be mixed freely in memory fill. Type 
siash (/) to enter the next character 


verbatim. 


Display next available address, allowing you 
to type any of the above commands. 
Enter Memory Page display; showing 

184 memory cells (starting at address) in 
hex and ASCII. Press and then 
press to display next 184 cells. 
Press to return to Bugbyter 
command level and Master Display. 
Convert positive decimal to hex. 

Convert negative decimal to hex (65536- 


decimalvalue). 


Convert hex to decimal. 
Convert hex to decimal. 
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Advance to next cell. 


Return to previous cell. 
Return to Bugbyter command 
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Register Reference 

PC =address Set 6502 Program Counter with hex address. 

A=value Set 6502 A-register with hex value. 

X=value Set 6502 X-register with hex value. 

Y =value Set 6502 Y-register with hex value. 

S=value Set 6502 Stack Pointer with hex value. 

P=value Set 6502 Processor Status register with hex 
value. 

C=value Set Bugbyter Cycle Counter to value. 

R=value Set Bugbyter keyboard Trace Rate to value. 


Trace/Single-Step Mode 


From Bugbyter’s command level, you can enter Single-Step mode 
by typing: 


addressS Enter Single-Step mode and execute single 
opcode starting at address. 

Enter Single-Step mode, continuing from 
previous address. 


= 


From Bugbyter’s command level, you can enter Trace mode by 
typing: 


addressT Enter Trace mode and interpret instructions 
Starting at address. 

Enter Trace mode, continuing from previous 
address. 


O 


Once in Single-Step or Trace mode (see S or T commands above), 
you can enter any of the following single-keystroke commands: 


Single-step, executing next instruction only. 

Skip next instruction. 

Enter Trace mode for continuous trace. 

Trace until RTS opcode encountered. 

Return to Bugbyter command level. 

Clear Cycle Counter. 

Use hand control 0 to adjust Trace Rate. 

Use Keyboard Rate (R=value) to adjust 
Trace Rate. 

Sound off (Quiet). 

Sound on. 


O 


op eee E 
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(1) Display primary Apple || screen. 

(2) Display secondary Apple Il screen. 

Display Apple || Text screen. 

Display Apple || Low-resolution graphics 
screen. 

(H) Display Apple || High-resolution graphics 
screen. 

Display Full screen graphics. 

(M) Display Mixed text and graphics. 





Disassembly Options for Trace/Single-Step 


From the Bugbyter command level, you can select one of the 
following options: 


O=A Display 6502 Accumulator in binary. 

O=X Display 6502 X-register in binary. 

O=Y Display 6502 Y-register in binary. 

O=S Display 6502 Stack Pointer in binary. 

O=P Display 6502 Processor Status register in 
binary. | 

O=B' Display instruction bytes in hex. 

O=E Display computed effective addresses or 


relative branches and instruction cycles. 





Breakpoints 


All breakpoints are set and cleared from the Bugbyter command 
level. 


BPn Set breakpoint “n” where: 
value Sets breakpoint field to value. 
(—) Moves to previous field. 
= Moves to next field. 
or 
Returns to Bugbyter command 
or line. 


POINT is definable breakpoint 
address. 

COUNT is the number of times 
Bugbyter encountered the 
breakpoint address. 
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TRIG is a definable count 
before breaking. Note: To 
cause a break, TRIG must be 
one or greater. 

BROKE is the number of times 
Bugbyter triggered. 


IN Insert real breakpoints (BRK opcodes (00)) 
into addresses specified in breakpoint 
subdisplay. Disables breakpoint 
modification. 

OUT Replace BRK opcodes with original 
instructions at addresses specified in 
breakpoint subdisplay. Enables breakpoint 
modification. Used for interpretive 
debugging (default). 

CLR Clear ail breakpoints. 

CLRn Clear breakpoint “n”. 


C—O Debugging in Execution Mode 


From the Bugbyter command level, you can enter Execution mode 
by typing one of the following commands: 


addressG Enter Execution mode, executing code as a 
subroutine starting at address. 

(G) Execute code as subroutine, continuing from 
previous address. An RTS opcode returns 
to Bugbyter. 

addressJ Enter Execution mode, jumping to code at 
address. 

Enter Execution mode, continuing from 


previous address. 





User Soft Switches 

Location Soft Switch Function 

start+3 Execute undefined 6502 opcodes ($80 =on; 
0=off—default). 

start+4 Use hand control button 0 to suspend Trace 
($80=on; 0=off—default). 

start+5 Use hand control 0 for Trace Rate 


($80 = on—default; 0=off). 
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start +6 


start +7 
start+8,+9 
start+$A,+$8 
start+$C,+$D 
CALL 1016 


CALL 8192 





Disable keyboard polling in Trace, Single- 
Step modes (MSB on + ASCII character 
code for escape character, MSB 
off=normal polling— default). 

Sound ($80 = on—defauit; 0 = off). 

Cycle Counter value (low-byte, high-byte). 

Starting address of real-time code 
(default =SFFFF). 

Ending address of real-time code 
(default = SFFFF). 

Restart Bugbyter using the Monitor's 
(CONTROL)-(Y ) vector. 

Restart Bugbyter using Bugbyter’s specific 
load address. 
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Appendix D 


Error Messages 


Editor Error Messages 
Two types of errors may occur when you are using the Editor: 


èe DOS errors, indicating that a problem occurred while reading 
your source file from disk, or while saving your edited text to a 
disk. 


è Editor command errors, indicating that you typed an 
unrecognized command or that you typed some command 
parameter incorrectly. 


lf a DOS error occurs while you are using the Editor, the Editor 
displays a normal DOS error message and allows you to correct 
the problem. If the Editor finds an error in a command you typed, 
the Editor displays an appropriate error message and ignores the 
illegal command. In neither case do you leave the Editor or lose 
your edited text simply because an error occurred. The error 
messages that you may see in both cases are discussed in the 
sections that follow. 





Editor’s DOS-Error Messages 


The Editor/Assembler uses DOS to manipulate files that are 
stored on a disk. In doing so, several DOS errors may commonly 
occur. When a DOS error occurs while you are using the Editor, the 
Editor displays a DOS-error message and returns to the Editor 
command level, allowing you to correct the problem and retype the 
command that resulted in the DOS error. 


The descriptions that follow show some of the ways in which DOS 


errors can happen. It presents the most common errors, but does 
not present the total list of errors that can occur. 
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WRITE PROTECTED 


AWRITE FROTECTED message indicates that you attempted to 
save to a disk that has a write-protect tab, or that you typed the 
ASM command when your source disk was write-protected. This 
message appears following the ASM command because a write- 
protected source disk prevents the Editor/Assembler from 
updating the ASMIDSTAMP file that tracks your source disks. 


FILE NOT FOUND 


The FILE HOT FOLIMO message occurs immediately after the 
ASM command if you do not have a file named ASMIDSTAMP on 
your program source disk. The Editor/Assembler does not require 
that this file be present, so you should ignore this message. This 
error can also occur if you try to issue a Direct DOS command, 
such as Lock or Unlock, that cannot find a file. 


1/0 ERROR 


An I... ERROR message typically indicates a bad disk media or a 
Gisk that is improperly inserted into the drive. If this error occurs 
while-you are saving a file, your output disk is probably bad and 
you should use the Save command with another disk. If it occurs 
during execution of a Load command, your file was only partiaily 
read in and may be permanently lost (backing up is wise). If this 
error occurs while you are using the Catalog command, you're in 
deep trouble and may have lost your disk directory. 


DISK FULL 


AQISK FULL error usually occurs during a Save commana: if you 
get this message, you should save your file onto another disk. 


FILE LOCKED 


The FILE LOCKED error can occur if you are in the habit of 
locking your files and try to save to a file that is locked. The locked 
file remains intact, as does your current edit file. Uniock the file or 
change the filename before trying to save the file again. It is 
excellent practice to lock ail the files on your disk except the one 
you are editing to avoid losing a file because you saved your edited 
file with the wrong name. 


SYNTAX ERROR 


The SYHTA ERROR message is the result of issuing a direct DOS 
command with incorrect syntax. 
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NO BUFFERS AVAILABLE 


This can occur if you call the system after MAXFILES has been set 
to one and you somehow issue a DOS command that tries to use 
two files at once. The system initially allocates five files, but 

pressing can cause files to be left open. If you issue a direct 
DOS .CLOSE command, the unused open files can be recovered. 


FILE TYPE MISMATCH 


This occurs if you try to load a file other than a text file or try to 
save using a name that is already in use by a another type of file, 
such as integer or binary. 


PROGRAM TOO LARGE 


lf this occurs, you tried to do a direct DOS Load command and 
have clobbered the Editor/Assembler, along with your edit file. 
Read the warnings regarding direct DOS commands in the chapter 
on the Editor. 





Editor Command-Error Messages 


The Editor checks the syntax and parameters of each command 
that you type to ensure that it is valid. The command descriptions 
in Chapter 2 include the specific error messages that may result if 
you type a command incorrectly. 


ERR: BAD FORMAT 


The EFF; GAC FORMAT message occurs if you type the first 
string field of the Change command as a null string. 


ERR: BAD RANGE 


The EFF; EAC FAHGE message occurs if the second line 
number in a range (begin=-end# or begin=-count) has an invalid 
ending line number. The Copy command requires the second line 
number of its range parameter to be an existing line in the Editor's 
text buffer. 


ERR: BAD SLOT/DRIVE/VOL = 


This error message indicates that a Slot, Drive, or Volume 
command has an invalid parameter. Valid slot numbers are 0 
through 7. Valid drive numbers are 1 and 2. Valid volume numbers 
are 0 through 254. 
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BUFFER ERROR 


A EUFFEF ERFRUIF message indicates that you typed the ASM 
command while you still had text in the Editor’s text buffer. Before 
using the Assembier, save this text and then clear the text buffer 
using the New command. The Editor signals this error to prevent 
you from accidentally overwriting your text by calling the 
Assembler without first saving your text. 


CMD SYNTAX ERROR 


The MO S'HTAS ERROR indicates that you typed extra 
characters following a valid command or command parameter. 


ERR: MEMORY FULL 


The EFF: MEM FILL message occurs when you fill all 
available text buffer space. This error appears when the Editor 
attempts to insert a line of text into the full buffer; when this 
happens you lose the line of text that you just typed or edited. The 
Load and Append commands also result in this error if the file 
being read overflows the text buffer. 


MULTI BUFFER ERROR 


The MULTI BUFFER EFRUF signals that you attempted tc use 
the ASM command when both Editor buffers are active. See the 
Kill2 command. 


NUMERIC OVERFLOW ERROR 
AHUMERIC OVERFLOW ERRUF results if a line number has a 
value larger than 63999. 


PARAMETER(S) OMITTED ERROR 


The FARFAMETER*® S> OMITTED ERROR message indicates that 
you neglected to type a necessary parameter for the command you 
just entered. 


ERR: SYNTAX 


AERF: S'vHTAS message following a Delete or Replace 
command indicates that you typed a range of line numbers with an 
implied ending line number. The same message following the Save 
command indicates that you must type a filename parameter; no 
filename was previously defined by a Load or Save command. 
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UNKNOWN COMMAND ERROR 


The IHEHOHH COMMAHO ERROR indicates that you typed a 
command name that is misspelled or not recognized by the Editor. 


Assembler Error Messages 
Two types of errors may occur when you are using the Assembler: 


e DOS errors indicate that a problem occurred while reading your 
source program from a disk, or while writing your object code to 
a disk. When a DOS error occurs, the Assembler immediately 
stops the assembly process. 


e Assembler syntax errors indicate that the Assembler 
encountered an unrecognized syntax or illegal usage in one of 
the assembly statements in your source file. When the 
Assembler encounters a syntax error, it prints an appropriate 
error message and continues with the assembly process. 


Both types of error messages are discussed in the sections that 
follow. 





Assembiler’s DOS-Error Messages 


When a DOS error occurs during an assembly, the Assembler 
stops the assembly, displays the DOS error message to indicate 
the problem, and prints the following message on the screen: 


ASSEMBLY ABORTED, PRESS RETURN 


The Assembler then waits for you to press before it 
attempts to close any open files. If the Assembler encounters 
another DOS error while trying to close files, the Assembler 
returns you to the Editor command level. 


The DOS error messages are also explained in the DOS User's 
Manual in the section on DOS messages. Many of these 
explanations are equally applicable to situations in which you use 
the Assembler; you may find it helpful to read this manual if you 
encounter any DOS errors. 


WRITE PROTECTED 


You have a write-protect tab on the disk to which the Assembler is 
trying to write the output object file. This error typically appears 
near the beginning of pass 2 of your assembly. 
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FILE NOT FOUND 


This is usually due to using the ASM command with a source 
filename that does not exist or is not on the disk in the current 
source drive and slot. It can also occur when a CHN, macro name, 
or Include command is used and the needed file is not present on 
the proper disk. 


1/0 ERROR 


This is usually a read error but it can also be a write error caused 
by bad disk media. If it is a hard read error on an input file, the 
same problem will show up when you try to load that file. If it is a 
write error on the object file, that file appears in the catalog as 
being only one sector, or it results in an |/O error when you try to 
BLOAD the file into memory. 


DISK FULL 


This occurs when there is no space left on the output file disk for 
the output file. This can occur at any time during pass 2, so it is 
wise to determine if there is enough space on the disk for the 
output. 


NO BUFFERS AVAILABLE 


This error is not likely to occur unless you entered the system with 
MAXFILES set to 3. A normal assembly requires that there be at 
least two buffers available. If the Assembler has previously aborted 
an assembly and is unable to close all the open files, this situation 
could arise. Execute a direct DOS .CLOSE after this occurs to 
attempt to recover the file buffer space. 


FILE LOCKED 
This occurs if you locked the object file. 


By the Way: If any other DOS error messages occur, probably the 
Editor/Assembler system is clobbered in memory, due to either a 
software bug or a hardware failure. Refer any repeatable errors of this 
kind to Apple Computer, inc. in writing: if at all possible send a disk that 
will reproduce the problem. Include ail relevant information: your 
machine type, memory size, peripheral cards installed, number of disk 
drives and controllers in use, and any modifications to this equipment. 


Always attempt to recreate any problem with a fresh copy of the 


Assembler/Editor disk before concluding that you have found a 
program bug. 
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Assembler Syntax-Error Messages 


As the Assembler processes your assembly-language source file, it 
checks the syntax of each statement and your usage of identifiers 
and operands. It reads your source statements during each of its 
two assembly passes, and checks your syntax during both passes. 
Since different checks are performed during each pass, some 
error messages appear only during the first pass, some during the 
second, and some during both. 


When the Assembler finds an error in a source statement, it prints 
an appropriate error message and skips to the next assembly 
statement. For this reason, the Assembier may not indicate all the 
syntax errors in your assembly statements the first time that you 
try to assemble your program. It may still find secondary errors in 
your source program after you correct all the errors flagged in a 
previous assembly. 


You may sometimes see an Assembler syntax-error message that 
indicates one of a number of possible errors. To identify the exact 
problem, you may have to check the specific source statement that 
caused the error message. 


As you watch your assembly, you may want to stop it if you see an 
error message that indicates a serious problem in your source file. 


When the assembly is completed, the Assembler prints an error 
total at the end of the assembly listing. It is the sum of all the 
errors that were encountered during both assembly passes. This 
total may therefore be larger or even double the actual number of 
assembly statements that contain syntax errors. 


ADDRESS MODE ERROR 


The 6502 does not support all address modes for ail opcodes. This 
error occurs when an invalid combination of opcode and address 
mode is found in a statement. 


ASSEMBLER PARAMETER ERROR 


The Assembler checks the parameters of the ASM command, 
passed from the Command Interpreter, for correct value ranges. 
This error occurs if the slot, drive or volume parameters are not 
within valid ranges. The error also occurs if a filename is more than 
30 characters long, or if an invalid hex object address is 
encountered. This error message is associated with line 0 of an 
assembly. 
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BRANCH RANGE ERROR 


The 6502 relative branch instruction has a limited addressing 
range. If the target address of a branch instruction is too far from 
the branch instruction, this error message is generated in pass 2. 


BUFFER SIZE ERROR 


The SBUFSIZ directive issues this message if the requested new 
buffer size would reduce the source buffer to a size smaller than 
the current source file residing in the buffer. The SBUFSIZ 
directive must be used to reduce buffer size only from a source file 
smaller than the desired reduced size. 


OVERFLOW ERROR 


The DS directive issues this error if the optional value expression is 
larger that eight bits. The expression directive characters can be 
used to ensure that this error is not generated. 


DIRECTIVE OPERAND ERROR 


This is a catch-all error message for many of the assembly 
directives that require specific operands. Generally this messages 
indicates that an expression is not properly delimited by a required 
delimiter, such as a comma, but instead contains some other 
character where a delimiter is expected. For example, the 
statement below produces this error: 


LABEL EGU 33:1 FORGOT THE SPACE AFTER: THE 
OPERANC 


The data definition directives check to ensure that spaces do not 
follow commas when an expression list exists in an operand, 
issuing this error if the spaces are found. 


The LST directive also issues this error if an invalid option 
character is encountered or if something other than a comma is 
used as a delimiter. The NO prefix for the LST options must be 
spelled exactly NO or no. 


DSECT/DEND ERROR 


This error indicates two things, depending upon the directive in the 
incorrect statement. This error is the result of attempting to nest 
the DSECT statement inside an active dummy section. The DSECT 
directive begins a dummy section, and the DEND directive 
terminates it. A second DSECT cannot be started while inside a 
dummy section. Terminating a dummy section with a DEND 
directive, when a dummy section is not active, also generates this 
error. 
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DUPLICATE EXT/ENT ERROR 


The EXTRN and ENTRY directives check to ensure that a symbol 
being defined as an external or entry symbol is not already so 
defined in a prior EXTRN, ENTRY, or ZDEF statement. Any one 
symbol can only be defined once as having one of these special 
characteristics. In addition to this duplicate directive function, this 
error is issued if more than one external identifier exists in any 
operand expression. 


DUPLICATE IDENTIFIER ERROR 


This error occurs when an identifier in the label field of a statement 
is an exact duplicate of a previously defined identifier. Use another 
name for the identifier in the offending statement. You can receive 
DUPLICATE IDENTIFIER ERRORS for ail occurrences of a 
duplicated identifier, although only some of these occurrences 
may require a correction. The symbol table dump does not show 
multiple entries for duplicate identifiers flagged with this error. 


EQUATE SYNTAX ERROR 


The Equate directive requires an identifier in the label field; this 
error occurs if the label field is empty—it is meaningless to define 
nothing as having some value. This error aiso occurs if the operand 
expression contains any external identifiers. 


EXPRESSION SYNTAX ERROR 


A valid term must follow all operators within an expression. A term 
in an expression is either a constant or an identifier. This error 
occurs when the text of a statement immediately foilowing an 
operator, such as the addition operator (+), is not recognized as 
one of these two items. Terms are recognized by their first 
character: 





First Character Term Type 

& Used in macros 

% Binary constant 

@ Octal constant 

$ Hexadecimal constant 


‘ ASCII character constant 


7 Program counter reference 

digit Decimal constant 

letter Identifier (uppercase or lowercase) 
= Literal constant 
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This error also occurs if one of the radix characters used to begin 
numeric constants is not followed by any digits appropriate to that 
type of constant. For example, %4 generates this error since only 0 
or 1 can follow the % (binary) radix character. 


EXTRN USED AS ZXTRN WARNING 


This error indicates that an identifier, defined as a 16-bit external 
value by the EXTRN directive, was used as an 8-bit quantity, either 
as a zero-page address or as an immediate operand. This type of 
usage produces nonrelocatable object code if the external value 
becomes an absolute value when a linker attempts to edit the REL 
modules together. 


The ZXTRN directive must be used in place of EXTRN for this type 
of identifier, and such identifiers must be defined using the ZDEF 
directive in the defining module (refer to ZDEF and ZREF for 
details). 


INCLUDE/CHN NESTING ERROR 


The Include directive cannot occur as a statement within an 
included file or within a macro file. The CHN directive cannot occur 
within a macro file. This error results if you use either directive 
incorrectly. 


INDEXING SYNTAX ERROR 


When specifying absolute-indexing or zero-page-indexing address 
modes, the addressing syntax required by the Assembler does not 
allow any character, except X or Y, to follow a comma. Refer to the 
section “Addressing Mode Summary” in Appendix B for details. 


INDIRECT REQUIRES ZPAGE ERROR 


The Assembler checks the type of an expression in the indirect- 
indexed and indexed-indirect addressing modes. If the expression 
is not a zero-page expression, this error occurs. (The 6502 
microprocessor requires the zero-page address.) 


INDIRECT SYNTAX ERROR 


This error occurs if invalid syntax is used for indirect-indexed and 
indexed-indirect addressing modes. The most common mistake is 
the improper use of the X- and Y-registers, for example, LDA 
(expr,Y) and LDA (expr),X. This error also results from omission of 
the right parenthesis in the indirect addressing modes. Proper 
syntax is shown in the section ‘‘Addressing Mode Summary” in 
Appendix B. 
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INVALID AFTER 1ST IDENTIFIER ERROR 


The SBUFSIZ and IBUFSIZ directives allow source and include 
buffer size management from the assembling program. These 
directives must be used before the first reference or definition of 
an identifier. 


INVALID DELIMITER ERROR 


This error message is the catch-all message for incorrect use of 
delimiters. All operand expressions must terminate with a space or 
a carriage return character. Various directives require the comma 
as a delimiter and do not allow spaces after commas. The indexing 
and indirect addressing syntaxes ail require specific character 
delimiters. The delimiters are the space, the carriage return, the 
comma, and the parenthesis. When the assembler expects one of 
these characters and does not find it, this error resuits. 


INVALID FROM INCLUDE/MACRO ERROR 


The SBUFSIZ and IBUFSIZ directives must not occur in an include 
file or in a macro file. 


INVALID IDENTIFIER ERROR 


This error indicates one of two errors. First, an identifier contains a 
character not allowed within an identifier. Identifiers must begin 
with a letter and contain only letters, digits and/or the period. 
Second, an identifier is not allowed as the operand of a directive, 
usually because of a prior or conflicting definition. For example, an 
identifier cannot be used in the label field of an instruction and 
also be the operand of the EXTRN directive. 


INVALID WITH CORES ERROR 


The SBUFSIZ, IBUFSIZ, INCLUDE, MACLIB, and CHN directives 
cannot be used when you specify the coresident assembly option. 
Attempting to use these directives during coresident assembly 
aborts the assembly. 


MACRO ARGUMENT ERROR 


There are only 11 valid characters that can follow the macro 
argument character in the body of a macro. They are the ten digits 
and the uppercase letter X. This error results if any other 
characters are found following the & character during a macro 
expansion. 
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MACRO NESTING 


The Assembler does not support calling a macro from within a 
macro. Macros can only be called from either a source file or an 
included file. 


OBJ BUFFER CONFLICT ERROR 


The OBJ directive requires that the placement of a coresident 
object code buffer be above the upper end of its symbol table and 
below the DOS 3.3 buffers. The DOS buffers end at $9100 and the 
symbol table normally begins at $3C00 unless modified by 
SBUFSIZ and IBUFSIZ. 


OBJ BUFFER OVERFLOW ERROR 


The first OBJ directive in an assembly defines the lower limit of the 
OBJ buffer for an assembly. If the OBJ buffer fills up all the way to 
the DOS 3.3 file buffers, this error message results and the 
assembly is aborted. 


OVERFLOW ERROR 


The ASCII source-to-binary conversion routines that convert 
numeric constants into binary values issue this error message if a 
constant definition generates more than 16-bits of information. 
For example, the constant $33333 has too many digits; only four 
are allowed in a hexadecimal constant. 


RELATIVE EXPRSN OPERATOR ERROR 


When the REL directive selects relocatable object-code output, 
the Assembler does not allow a relative address expression or 
subexpression to be divided, multiplied, ANDed, ORed, or 
exciusive-ORed; doing so causes the result to be nonrelocatable. 
This prohibition only applies if you used the REL directive in your 
source file. 


RESERVED IDENTIFIER ERROR 


The Assembler does not allow the labels A, a, X, x, Y, and y as 
identifiers. /f you insist on using these identifiers, there is a patch 
address offset in bytes 3 and 4 of the ASM file (using 0 base 
counting of code bytes) that indicates how far into the object code 
image to place a patch to cause this checking to be nullified. The 
patch consists of a CLC ($18) and a RTS ($60) opcode. They must 
be patched over the first two bytes of a JSR instruction. 
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SLOT/DRIVE/VOLUME ERROR 


This error occurs if any of the named parameters are out of range 
on the file directives that use these parameters. Slot must be 1 
through 7, drive 1 or 2, and Volume 0 through 254. This error is 
most commonly caused by entering $£ instead of ©. | 


SYMBOL/RLD TABLE FULL ERROR 


This error occurs when insufficient space is available for the 
symbol table and, if the REL directive was used, for the relocation 
dictionary tables. The SBUFSIZ and IBUFSIZ directives default to 
a total size of 4K, but you can reduce these buffers to as little as 
one page each to provide additional symboi/RLD tabie space. 


SWEET16 OPCODE WARNING 


This warning indicates that a SWEET 16 opcode was encountered 
in an assembly without at least one occurrence of the SW16 
directive. This is a protective measure to prevent accidential use of 
SW16 mnemonics, which are very similar to 6502 mnemonics. 


SW16 REGISTER ERROR 


The SWEET 16 pseudomachine has sixteen registers, designated 
RO thru R15, and the Assembler validates that SWEET 16 register 
expressions are only 4-bit resuits. 


UNDEFINED IDENTIFIER ERROR 


This error, generated in assembly pass 2, indicates an identifier 
was referenced, but never defined in your assembly source. It is 
most commonly caused by misspelling an identifier. 


UNDEFINED OPCODE ERROR 


This error occurs when macros are not enabled (the default 
condition), and a mnemonic is used that is not found in the 
Assembler’s mnemonic table. It is most commonly a spelling error. 
This error becomes a DOS 3.3F ILE HOT FOLIO error if you have 
enabled macros by using the MACLIB directive. 


>255 EXTRNS/ENTRYS ERROR 


When creating the Relocation Dictionary, the Assembler assigns a 
unique number to each EXTRN and ENTRY identifier; the numbers 
range from 1 to 255. The Assembler aborts if you use more than 
255 such symbols in your source file. 
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Appendix E 


Object File and Symbol 
Table Formats 


Object File Format 


The Assembler generates two kinds of DOS object files: binary 
memory-image files and relocatable binary code files. Uniess you 
use the REL assembly directive at the start of your assembly- 
language source file, the Assembler produces a binary file using 
the standard DOS binary format. 


You can use the BLOAD command to load binary files produced by 
the Assembler, or, if your program is properly coded, you can 
BRUN your program from the normal BASIC/DOS environment 
(but not from within the Editor/Assembler system). To write your 
program so you can execute it using the BRUN command, your 
program must begin with executable code, not data, at the lowest 
address for which object code is generated. 


The relocatable binary file is a file type not recognized by DOS. 
Table E-1 defines the format of this file type. In this table, the 
symbol => means indicates or implies. 





Sector Byte (Hex) Contents of Byte 
1 0 Starting RAM address, low byte 
1 Starting RAM address, high byte 
2 Length of RAM image, low byte 
3 Length of RAM image, high byte 
4 Length of code image, low byte 
5 Length of code image, high byte 
1toM 6 toc1+5 Binary code image, of length in bytes 4 and 
5 above 
c1+6 Begin Relocation Dictionary, which 


consists of N 4-byte entries. N is variable (0 
or greater). Each four bytes repeat the 
following structure: 
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Byte 


N°4+1 
N*4+>2 


1 to si 


siz 1 


$ 10-bit 
$08-bit 


si+2 


s1+3 


End mark 


Contents of Byte 


RLD-flags byte containing four flag bits as 
follows: 


$80-bit Size of relocatable field 
Set => 2 bytes, Clear = > 1 byte 


$40-bit Upper/Lower 8 of a 16-bit value 
Set => high 8, Clear = > low 8 


$20-bit Normai/reversed 2-byte field 
Set => high-low, Clear = > iow-high 
(The DDB directive causes Set.) 


$10-bit Field is EXTRN 16-bit reference 
Set => EXTRN, Clear = > not EXTRN 


$01-bit NOT ENO OF FLO flag bit 
Always Set on for RLD entry 
Clear marks end of RLD 


Field offset in code, low byte 
Field offset in code, high byte 


Low 8 bits of 16-bit value for an 8-bit field 
containing upper 8 bits. Zero if $40-bit 
clear in RLD byte one. Or if the $10-bit is 
set, then this is the ESD symbol number. 


Binary 00 marks end of RLD. 


Beginning of optional External Symbol 
Directory (ESD). This area contains bytes 
only if an EXTRN and/or ENTRY directive 
occurs in the program. 


The EXTRN/ENTRY symbolic name of 
length si bytes. All bytes have their $80-bit 
set except the last one. 


Symbol type fiag byte defines which type of 
symbol EXTRN/ENTRY 


Set => EXTRN symbol type 
Set = > ENTRY symbol type 


EXTRN/ENTRY symboli number referred to 
by an RLD entry with EXT-bit set on. 


High byte of offset for ENTRY type symbol, 
(low is in si+ 2) 


Binary zero-byte marks end of the ESD 
entries, of which there may be Zero. 
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Mane Symbol Table Formats 


The symbol table generated during pass 1 of the assembly 
process is described here, along with the table format as it 
remains after the symbol table was modified by the symbol-table 
sort and print routine (pass 3) . The symbol table is in its modified 
form and the RLD may be clobbered if the symbol table sort and 
dump is allowed to execute and it overwrites the RLD with its sort 
index table. The symbol table is a variable-length entry-format 
table with flag bits to signal the end of the variable-iength-name 
character string. 


The basic format is (Symbolicname\FlagbyteXLow value) 
(High value) 





Symbolicname consists of 1 to n characters, each with its $80-bit set, except 
the last character's $80-bdit is reset. 


Flagbyte contains the bits that define the characteristics of the symbol, 
its value, and how it can be used to generate instructions, as 
follows: 

* $80-bit Undefined-Symboi bit 


This means that the symbol is referenced but not defined. This 
flag is reset when a symbol is defined; if it remains set at the 
end of pass 1, the symbol is undefined and causes the NU 
SUCH LABEL error during pass 2. Symbols with this bit set are 
printed by pass 3 with an * next to the address (which is 
meaningless: it is simply the the value of the program counter 
at the first reference). 


$40-bit Unreferenced-Symboi bit 


The symbol is defined but never used as the operand of any 
instruction in the program. This bit causes the ? to print next 
to the address value for an unreferenced symbol in the dump. 


$20-bit Relative-Symbol bit 


The symbol's value is a reiative symbol rather than an absolute 
address. Relative means relative to the beginning of the 
module. It is used internaily by the assembier, when generating 
the Relocatable type of output file, to cause an ALD entry to be 
created for any references to the symbol. 


$10-bit External-Symbol bit 





The symbol is defined as an external symbol via the EXTRN 
directive. This causes the symbol to be put into the ESD and 
prevents the symbol from being considered undefined, even 
though no value is assigned to it. Using such a symbol causes 
an RLD entry to be marked as EXT and causes the external 
symbol number to be put in the RLD entry in place of tine 
relative offset. External symbols can only represent undefined 
16-bit values (not 8-bit or zero-page values). 
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$08-bit 


$04-dit 


$02-bdit 


$0 1-bit 


ENTRY-Symbol bit 


The symbol is an entry point into the module that can be 
referred to by an EXTRN in another module. This causes the 
symbol to be included in the ESD for resolution by a linkage 
editor. Note: A linkage editor is not implemented. 


Macro-name bit 


This bit is reserved for signalling whether the symbol is actually 
a macro filename: the value bytes hold drive and slot, 
respectively. Note: this feature is not impiemented. 


NO-Such-Label Error bit 


The symboli has caused one or more HI SUCH LABEL errors. 
This is used to prevent a duplication of a single error in the 
error summary table during pass 2. 


Forward-Referenced bit 


A forward reference forced the symbol to be considered a 16- 
bit value. Zero-page labels print in the symbol dump with 
blanks for the first two bytes. They print with two zeros when 
this bit is set. If the definition is moved forward so the symbol is 
defined before it is referred to, reassembing the program 
generates shorter zero-page instructions. 





When the Symbol Sort and Dump routine executes, it modifies the 
symboi table format to speed up the scanning of the table for its 
second phase. The last character of each symbol has its high- 
order bit set on and the Flagbyte is changed. If the Flagbyte has its 
$80-bit set, its value is changed by ORing it with $7E to set all but 
the $01-bit on. The $01-bit is retained, and the $80-bit is set off to 
mark the end of the symbolic name. Thus, if pass 3 is run, all 
Fiagbytes have their $80-bits reset, and undefined symbols have a 
Flagbyte of $7E or $7F. 
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Editing BASIC Programs 


Using the Editor, you can perform many useful editing functions on 
the text of your BASIC programs. You can use the Find command 
to locate all statements referring to a given BASIC variable or line 
number, for example. You can use the global Change command to 
change all occurrences of a variable name to a new name, or to 
change ail occurrences of a GOSUB to some other line number. 


Using the Editor to Edit BASIC Programs 


To use the Editor to edit BASIC programs, you must first convert 
your BASIC program into a sequential text file. The DOS 
Programmer’s Manuali contains a section ‘Capturing Lines of a 
BASIC Program” explaining how you can do this. After you convert 
your BASIC program into a sequential text file, you can then load 
the text using the Editor and edit the program as you would any 
other text file. 


Remember: Sefore you edit your program, set the Tabs command to 
zero to keep the left margin of your text at the left side of the screen. 


When you are editing BASIC programs, you must be careful not to 
change the line number of a statement without also changing all 
the references to it elsewhere in your program. If you want to 
change any line numbers within a BASIC program, it is better to 
use the Applesoft/Integer BASIC RENUMBER programs instead of 
using the Editor. 


When you are editing a BASIC program using the Editor, the Editor 
shows two line numbers on every line. The first line number is the 
Editor’s relative line number; and the second is the line number of 
the BASIC statement. Only the line number of the BASIC 
statement is actually stored in the text file. As you are editing, you 
can use only the Editor’s relative line numbers as the line number 
parameters for Editor commands. 


Using the Editor to Edit BASIC Programs 211 





212 





When you finish editing, you must save the text file back on your 
disk and reenter BASIC, using the Editor End command. To 
reenter your edited text file into BASIC, type the command 


EMEC myer car am 


where myprogram is the name of your BASIC program text file. 
This command causes DOS to read the entire text file from the 
disk into BASIC, just as if you typed it from the keyboard. 


Since BASIC places each line from your text file into a BASIC 
program according to its line number, each line of your BASIC text 
must begin with a line number. The order of the lines within your 
text file is not important; changing the order of the lines without 
changing their line numbers will not change the way your program 
is interpreted by BASIC. 


Editing BASIC Programs 
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The SWEET 16 Interpreter 


Mines A 16-Bit Pseudomachine 


The Assembler can generate object code for the 16-bit pseudo- 
machine known to experienced Apple || users as SWEET 16. This 
pseudomachine is described in the October 1977 issue of BYTE 
magazine in the article entitled SWEET 16: The 6502 Dream 
Machine. The Apple II Integer BASIC ROM contains a SWEET 16 
interpreter that implements this 16-bit pseudomachine in 


software. 
The Editor contains a SWEET 16 You can take advantage of this 16-bit processor in your own 
interpreter. assembly-language programs by capturing SWEET 16 interpreter 


code from the Editor in your own code; this allows you to use the 
SWEET 16 routines on any type of Apple Il. To use SWEET 16, your 
program must execute a subroutine call to the starting address of 
the SWEET 16 software interpreter. This starting address is at 
location $F689 in the Apple II Integer Basic ROM. When you are 
using the Assembler, you can generate this subroutine call 
automatically by using the SW16 Assembly directive described in 
Chapter 3. 


Immediately following this call to the SWEET 16 interpreter, your 
program code should contain only SWEET 16 instructions, to be 
executed in sequence by the SWEET 16 interpreter. To return 
control of your program to the 6502 microprocessor, you must 
include the SWEET 16 RTN operation code at the end of each 
sequence of SWEET 16 instructions. Following this RTN operation 
code, your program must contain only 6502 instructions, since the 
6502 microprocessor resumes executing your program directly. 
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SWEET 16 Interpreter Operation 


When your program calls the SWEET 16 interpreter, the interpreter 
saves the current 6502 register contents and begins interpreting 
the SWEET 16 instructions starting at the address immediately 
following your SWEET 16 subroutine call. These instructions can 
manipulate data in memory, manipulate SWEET 16's own internal 
registers, or jump to other program locations. 


At the end of the sequence of SWEET 16 instructions, your 
program must contain a SWEET 16 RTN instruction. When the 
SWEET 16 interpreter finds this instruction, the interpreter 
restores the original 6502 register contents and returns the 6502 
microprocessor to the instruction immediately following the 
SWEET 16 RTN. The 6502 microprocessor then resumes normal 
execution of 6502 instructions. 


A simple use of the SWEET 16 interpreter is demonstrated in this 
example: 


2200:63 AG JŽ 19 LOR IN,‘ :GET A CHARACTER 
A303;03 CO 11 OMP #'Mm' iM IS FOR MOVE? 
2205:00 49 12 BNE NOTMVE iNO, OON'T MVE 
2907:20 39 Fs 13 SWié ' SWEET ON ME? 
AIGA: AL 14 MOVLP LOI R1 :GET SQURPCE BYTE 
A306: S52 15 STI R2 PUT TO TARGET 

Ss | a F3 15 OCR RS ‘COUNT OOWN LENGTH 
B300;a7 FS 17? ENZ MOWLP ; UNTIL ZERO LENGTH 
ASAF : HÅ 13 RTH EACK TO 5502 
2910:09 CS 13 NOTMVE CMP #'E' ‘ALL QONE? 

2912:00 13 29 SE EXIT ‘YES. GET QUT 
2314:73 21 INY ‘MO, CONTINUE 


The SWEET 16 instructions appear on lines 14 through 18, while 
the remainder of the instructions are normal 6502 instructions. 
Note that the SW16 directive simply generates a 6502 JSR 
instruction to the address $F689. 


The SWEET 16 instruction mnemonics and operation codes are 
different from those of standard 6502 instructions. You must be 
careful not to intermix SWEET 16 instructions with 6502 
instructions in your programs except as outlined above: every 
block of SWEET 16 instructions must be preceeded by a call to the 
SWEET 16 interpreter and must be ended with a SWEET 16 RTN 
instruction. The Assembler helps you avoid using SWEET 16 
instructions unintentionally by issuing the SsWEET1Le OFPCOCE 
warning if you should use a SWEET 16 instruction in your program 
without somewhere also including the SW16 Assembly directive. 
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Mana SWEET 16 Instruction Summary 





Register Instructions 





OpCode Mnemonic 
in SET Rn,Const 
2n LD Rn 
3n ST Rn 
4n LDI Rn 
5n STI Rn 
6n LDD Rn 
7n STD Rn 
8n LDP Rn 
9n STP Rn 

j An ADD Rn 
Bn SUB Rn 
Cn POPD Rn 
Dn CPR An 
En INR Rn 
Fn DCR Rn 


Explanation 

Load Rn with the two byte constant 
Load RO from Rn 

Store RO to Rn 

Load low byte of RO from address in Rn 
Store low byte of RO to address in Rn 
Load RO with word at address in Rn 
Store RO to word at address in Rn 


Decrement An, load low byte of RO indirect 
Rn 


Decrement Rn, store low byte of RO indirect 
Rn 


Add Rn to RO, storing result in RO; set status 


Substract Rn from RO, resuit in RO; set 
status 


Decrement Rn and load RO from address in 
Rn 


Compare RO to contents of Rn; set status 
Increment the contents of Rn by 1 


Decrement the contents of Rn by 1 








Control Instructions 
OpCode Mnemonic 
00 RTN 

01 BR ea 

02 BNC ea 

03 BC ea 

04 BP ea 

05 BM ea 

06 BZ ea 


Expianation 

Return to 6502 mode 

Branch to the effective address (ea) 
Branch if No Carry 

Branch if Carry 

Branch if Plus 

Branch if Minus 


Branch if Zero 
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07 BNZ ea Branch if NonZero 


08 BM1 ea Branch if Minus 1 

09 BNM1 ea Branch if Not Minus 1 

0A BK Break into 6502 Monitor 

0B RS Return from SWEET 16 subroutine 

oc BS ea Branch to Subroutine . 

0D CPIM const Compare RO to two-byte constant; set 
status 

0E BRL ea Branch long to effective address 

OF BSL ea Branch Subroutine Long to effective 
address 





The mnemonic definitions for the SWEET 16 LDI and STI 
instructions differ from those originally defined in the BYTE article, 
because the original LD @ and ST @ mnemonics conflict with the 
Assembler’s use of the @ character to indicate octal constants. In 
addition, the STP mnemonic is used in place of POP, to be 
consistent with the LDP mnemonic (the Assembler also accepts 
POP). 


The last three instructions are new instructions that are not 
recognized by the Integer BASIC version of the SWEET 16 
interpreter. These instructions are recognized by the SWEET 16 
interpreter that is contained in the Editor module. This interpreter 
resides in the Language Card from address $0C2E through 
$DE93, when the Editor is in memory. You therefore have two 
versions of the SWEET 16 interpreter to choose from, if you don’t 
mind including the Editor SWEET 16 interpreter into your program 
code: 


è The Integer BASIC version in ROM, designed to conserve ROM 
memory, at the expense of execution speed 


è The Editor version, designed for execution speed without 
regard to code size. 


The SWEET16 interpreter 


Figure H-1. Memory Map of the 64K 
Editor/Assembier 
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System Memory Usage 


The Editor/Assembler 


Figure H-1 shows the memory areas used by the various modules 
that comprise the Editor and Assembler. In the 64K version of the 
Editor/Assembler, both the Editor and the Assembler are in 
memory at the same time. In the 48K version of the 
Editor/Assembler, the Assembier shares the same memory space 
with the Editor. When you call the Assembler in a 48K system, the 
Assembler code overlays the Editor’s text buffer, as shown in 
Figure H-1. 


This memory map of the 64K system is provided for reference only. 
Apple Computer, Inc. reserves the right to change or expand the 
areas used at any time and without notice. 
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N The Bugbyter Debugger 


Figure H-2 shows the memory areas in which you can load the 
Bugbyter debugging program. Bugbyter occupies 1.6K of 
contiguous memory and must be located so it does not overlap 
any of your own program's code or data areas. Chapter 4 includes 
a description of how you can relocate the Bugbyter to any of the 
areas shown in the figure. 


Figure H-2. Memory Map Showing 48K motherboard RAM: Optional Language or RAM Card: 
Locations of Bugbyter and Your 
Program SBFFF: + + $FFFF: + 
DOS Monitor 
$9600: + + $F800: + > 
Bugbyter Bugbyter 
can can reside 
reside anywhere 
anywhere in here + undefined + 
in 
here $D000: + bank 2 ++ banki + 
$800: + -= 
text screen 
$400: + = 
$200: + - 
stack 
$100: + + < first $20 bytes reserved ($100-11F) 
zero page 
0: + + 


Note: Bugbyter reserves the last 32 bytes of the program stack. 
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Editor/Assembler 
File Components 


Renan The EDASM Files 


When you run the Editor/Assembler, the EDASM program 
determines whether you are currently using a 48K or a 64K 
Apple Il, and loads the appropriate code portions for your 
particular machine. (You may have noticed that there are two sets 
. of object modules for the EDASM program on your DOS 
Programmer’s Tool Kit Volume II disk.) If you ever want to move 
the Editor/Assembier to another disk, you can save space by 
copying only the EDASM modules that you need for your particular 
Apple || configuration: 


è For a 48K Appie ||, the Editor/Assembier modules you need are: 


EDASM 
EDASM.1 
EDASM48.2 
EDASM48.3 
EDASM48.4 
EDASM48.5 
EDASM48.6 


è For a 64K Apple ll, the Editor/Assembler modules you need are: 


EDASM 
EDASM.1 
EDASM64.2 
EDASM64.3 
EDASM64.4 
EDASM64.5 
EDASM64.6 
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Rie Making a HELLO Program 


See the INIT command in the DOS 
User's Manual. See aiso the section on 
making a turnkey disk in the DOS 
Programmer’s Manual. 





lf you want, you can configure your programming system disk so 
that whenever you boot your system disk, you automatically start 
up the Editor/Assembler program. This is done by making the 
EDASM program into your system disk’s greeting program or 
turnkey program. 


lf you recall, everytime you initialize a disk, you must specify the 
name of a greeting program. Typically, this greeting program is 
named HELLO. Whenever you boot a disk that has a greeting 
program, your Apple || automatically runs this BASIC program as 
the first thing after loading DOS itself. 


To set up EDASM as your disk’s greeting program, all you need do 
is rename EDASM with the name of your disk’'s greeting program. 
lf you are initializing a new disk, you can simply specify the name of 
the greeting program to be EDASM. Once the Editor/Assembler 
program has the same file name as your disk’s greeting program, 
you are automatically placed at the Editor command level 
whenever you boot this disk. 
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A-Register 110, 146 
absolute identifier(s) 67 
absolute location in memory, 
identifying 45 
absolute ORG directive 75 
activating a printer 34 
Add command 15, 29, 176 
ADORESS MODE error 199 
address-mode syntax 51 
All ASSEMBLY ID 168 
Alphabetic Symbol Tabie 
option 94 
ALS Smarterm 80-Coiumn display 
card xiv 
&0 parameter 99 
&X parameter 100 
Append command 26, 175 
Apple || SWEET16 routine(s) 78 
Apple Il system, 48K 12 
Apple lle, 80-Column Text 
Card xiv 
arithmetic operator(s) 70 
ASC directive 84 
ASCII directive See ASC directive 
ASM srcfile command 178 
ASMIDSTAMP 12 
ASMIDSTAMP file 59 
Assembler 
ASC directive 84 
control character(s) 29 
Date directive 85 
DCI directive 84 
DDB directive 82 
DEF directive 79-80 
defining data 81 
DEND directive 76 
DFB directive 82 


index 





DOS error messages 197-198 
DS directive 83 
DSECT directive 75-76 
dummy section(s) 75-76 
DW directive 82 
entry point symbol(s) 64 
EQU directive 79 
error messages 197-205 
external symbol(s) 64 
IDNUM directive 85 
listing cycle times 93 
location counter 71-72 
modular assembly 88 
MSB directive 83 
no object code 56, 76 
OBJ directive 77 
ORG directive 74-75 
program counter 71-72 
REF directive 80 
REL directive 77-78, 160 
STR directive 84 
suppressing generation of object 
file(s) 56 
SW 16 directive 78 
syntax-error messages 
199-205 
tab character(s) 43, 66 
zero-page address 65 
ZXTRN directive 81 
Assembler directives 65, 67 
Assembler ID stamp 12, 59 
ASSEMBLER PARAMETER 
ERROR 199 
assembling programs from 
memory 57 
assembling your program 53 





224 


Assembly directives 73-96 
DEND directive 76 
DSECT directive 75-76 
OBJ directive 77 
ORG directive 74-75 

absolute 75 

relative 74 

REL directive 77-78 
SW16 directive 78 
assembly-ijanguage 
program(s) 3 
programming 3 
source file(s) 3, 5, 65-72 
instruction(s) 5, 67 
mnemonics 51 
subroutine(s) 6 

assembly listing(s) 51, 54 

Alphabetic Symboi Table 
option 94 

Assembler warnings 93 
generating 59 

header(s) 62, 96 
interpreting 61-62 
interrupting 63 

macro expansion(s) 94, 99 
making your listing readable 95 
single-stepping 63 

tab settings 63 

title(s) 96 

turning off 63-64 
Value-Ordered Symbol Tabie 
option 94 

Assembly macros 67, 68, 97 
&0 parameter 99 
&X parameter 100 

Assembly statement(s) 
comment field 66 
label field 66-67 
mnemonic field 66-67 
operand field 66 
operation field 66 
syntax 65-66 


backing up your work 28 
backup files 28 

BASIC subroutine(s) 6 
binary file(s) 5 

binary object program(s) 52 
binary-logic operator(s) 70 
Brakpoint subdisplay 143 
BRANCH RANGE ERROR 200 
Breakpoint Flag(s) 111 
Breakpoint subdisplay 113 


Index 





breakpoint(s) 142 
real 142, 148 
transparent 142 
BUFFER ERROR 196 
BUFFER SIZE ERROR 200 
bug(s) 105 
Bugbyter 
altering Master Display 
layout 137-138 
Breakpoint Flag(s) 111, 148 
Breakpoint subdisplay 113 
changing registers 136 
Code Disassembly 
subdisplay 112, 118 
command level 114-115 
command line 114 
counting instruction cycles 147 
Cycle Count Register 111, 147 
display option(s) 145-146 
editing commands 116 
entering DOS commands 117 
entering the Monitor 131 
executing undefined 
opcodes 156 
keyboard interrupt 
character 153 
Master Display 109 
Memory Cell subdisplay 113 
Memory Page display 128 
memory restrictions 107-108 ~^ 
Memory subddisplay 122 
Off command 153 
Quit command 128 
Register Subdispiay 110 
relocating 130 
restarting 131 
Single-Step operation(s) 140 
single-stepping your 
program 119 
soft switch(es) 151, 154 
Stack subdisplay 111 
Trace mode 125 
Trace operation(s) 140 
Trace Rate Register 111 
turning off display 153 
turning off keyboard 
polling 154 
using in a Language Card 130 
using the keyboard 153 
viewing memory 127, 132 
Bugbyter Execution mode 115 
Bugbyter Registers 111 
Bugbyter Trace mode 115 
button 0 See hand control 
button 0 
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calling the Assembler 55-56 
CAPS LOCK command 23 
caps lock mode 23 
CAT command 18, 175 
Catalog command See CAT 
command 
Chain directive See CHN 
directive 
Change command 36, 177 
changing registers 136 
changing text 36 
changing the command 
delimiter 37 
changing the current disk 28 
changing the tab settings 42 
Character directive See CHR 
directive 
CHN directive 88 
CHR directive 95 
clearing the text buffer 19, 32 
CLR command 144 
CMD SYNTAX ERROR 196 
Code Disassembly 
subdispiay 112, 118 
Coiumn 80 command 177 
Column 40 command 177 
command delimiter 37 
command level 114-115 
command line 114 
command names 22 
command(s), more than one on a 
line 22 
command-error messages 
195-197 
comment field 66, 72-73 
conditional assembiy 85-88 
conditional assembly block 86 
conditional-assembly 
directive(s) 85-88 
constant(s) 69 
numeric 69-70 
string 69-70 
control character(s) 29 


(E}command 23, 177 
(R)command 33, 176 
[CONTROL)-(W) command 23, 177 


Copy command 31, 176 
copying lines 31 

coresident assembly 57 
counting instruction cycles 147 
current disk siot 25 

current drive 25 

current filename 25 

current volume 25 
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cursor 14 
Cycle Count Register 111, 147 
Cycie Times option 93 
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Date directive 85 
DB directive 82 
DCI directive 84 
DOB directive 82 
debugging 105 
real-time code 150-152 
DEF directive 79-80 
default tab settings 16 
Define Byte directive 
See DFB directive 
Define Double Byte directive 
See ODB directive 
Define Storage directive 
See DS directive 
Define Word directive 
See OW directive 
defining data 81 
Delete command 30, 31, 176 
DEND directive 76 
device-control-string 61 
OFB directive 82 
direct DOS commands, 
executing 24 
DIRECTIVE OPERAND error 200 
directive(s) 52 
DISK FULL error 194, 198 
display option(s) 145-146 
displaying text 16 
DO directive 85-87 
DOS commands 24, 117, 175, 
180 
DOS error messages 197-198 
DOS EXEC file 61 
Drive command 28, 176 
DS directive 83 
DSECT directive 75-76 
OSECT/DEND error 200 
dummy section(s) 75-76 
DUPLICATE EXT/ENT error 201 
DUPLICATE IDENTIFIER 
error 201 
DW directive 82 


Edit command 38, 177 
Edit mode 17, 38-40 
editing commands 116 
editing two files atonce 41 
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Editor 

activating aprinter 34 
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